---
# System prepended metadata

title: uv python套件及虛擬環境管理紀錄
tags: [Python, Ubuntu]

---


uv 是一個由 Astral 公司（Ruff 的開發者）所打造的極速 Python 套件安裝與管理工具

旨在取代傳統的 pip 和 venv 工作流程

以 Rust 編寫，提供了無與倫比的速度和高整合的使用體驗

# 安裝
```
sudo apt update
sudo apt install python3-pip
pip install uv
```

## 	建立一個虛擬環境 (預設名稱為 .venv)。
```bash=
# 建立一個使用 Python 3.11 的虛擬環境
uv venv -p python3.11

# 建立一個指定名稱 (例如 .my-env) 的虛擬環境
uv venv -p python3.11 .my-env
```


# 啟動虛擬環境
```bash=
# Linux / macOS
source .venv/bin/activate

# Windows (Command Prompt)
.my-env\Scripts\activate

# Windows (PowerShell)
.venv\Scripts\Activate.ps1
```
##  初始化專案
這個指令會引導您建立一個 pyproject.toml 檔案，這是現代 Python 專案的標準設定檔
它會詢問您專案名稱、版本、作者等資訊，並建立一個基本的結構。
```
uv init
```
初始化後，您的 pyproject.toml 可能會像這樣

:::spoiler 範本
```bash=
[project]
name = "my-awesome-project"
version = "0.1.0"
description = "Add your description here"
authors = [
    { name = "Your Name", email = "your@email.com" },
]
dependencies = [] # 您的專案依賴會在這裡
requires-python = ">=3.8"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.rye]
managed = true
dev-dependencies = [] # 開發環境的依賴會在這裡
```
:::


# 套件紀錄

## 安裝套件
```
# 安裝單一套件 (例如 requests)
uv pip install requests

# 安裝多個套件
uv pip install "fastapi[all]" uvicorn

# 安裝僅在開發時使用的套件 (例如 pytest)
uv pip install --dev pytest
```

uv 的解析速度極快，即使是複雜的依賴關係也能在毫秒級完成。

使用 --dev 參數安裝的套件會被記錄在 pyproject.toml 的 [tool.rye.dev-dependencies] 區塊，方便區分專案執行所需和開發測試所需的套件。
### 移除套件
```
# 移除單一套件
uv pip uninstall requests
```
### 同步環境 (uv sync)
這是 uv 的一個強大功能。當您修改了 pyproject.toml 檔案（例如手動新增或刪除依賴）
或是您的 uv.lock 檔案與目前環境不一致時，uv sync 可以快速讓您的虛擬環境與設定檔同步
```
# 根據 pyproject.toml 和 uv.lock 來安裝/移除套件
uv sync
```

## 匯出requirements.txt
```
uv pip freeze | sed 's/\x1b\[[0-9;]*m//g' > requirements.txt
```

這個單一指令的工作流程如下：

`uv pip freeze`

這個指令會先執行，將目前環境中所有已安裝的套件列表輸出到「標準輸出」(stdout)。這時候的輸出可能還包含著色用的 ANSI 控制碼。

`| (管線 Pipe) `

這個符號是關鍵。它會將左邊指令 (uv pip freeze) 的輸出，直接當作右邊指令 (sed) 的輸入，就像一條水管一樣把資料傳過去。

`sed 's/\x1b\[[0-9;]*m//g'`

sed 指令會接收從管線傳來的資料，執行腳本來移除所有 ANSI 控制碼，然後將清理乾淨的結果送到它自己的「標準輸出」。

`> requirements.txt`

最後，這個「重新導向」(redirection) 符號會將 sed 清理完畢的最終輸出，寫入到 requirements.txt 這個檔案中。

## 匯入requirements.txt
```
uv pip install -r requirements.txt
```