uv 完整指南：現代 Python 軟件包管理
uv 是一個極速的 Python 軟件包和項目管理器，由 Rust 編寫。它提供了一個統一的界面來管理 Python 依賴項、虛擬環境、Python 版本和項目。
什麼是 uv？
核心架構
| 組件 | 語言 | 用途 | 替代工具 |
|---|---|---|---|
| 軟件包安裝程序 | Rust | 快速依賴項解析和安裝 | pip |
| 項目管理器 | Rust | 帶有鎖定文件的現代項目管理 | poetry, pip-tools |
| 環境管理器 | Rust | 虛擬環境創建和管理 | virtualenv, venv |
| Python 版本管理器 | Rust | 安裝和切換 Python 版本 | pyenv |
| 工具運行程序 | Rust | 從軟件包中執行 CLI 工具 | pipx |
| 軟件包發佈者 | Rust | 構建和發佈分發版 | twine |
核心特性
- 🚀 統一工具鏈：單個命令即可替代 8 個以上的 Python 工具。
- ⚡️ 極致性能：比 pip 快 10-100 倍（基準測試）。
- 🗂️ 項目管理：跨平台通用鎖定文件支持。
- 🐍 Python 管理：安裝和管理多個 Python 版本。
- 💾 全局緩存：磁盤空間高效的依賴項去重。
為什麼使用 uv？
性能基準測試
| 操作 | pip 時間 | uv 時間 | 速度提升 |
|---|---|---|---|
安裝 requests（冷緩存） | 1.2s | 0.08s | 15 倍更快 |
安裝 Flask（熱緩存） | 0.8s | 0.01s | 80 倍更快 |
| 解析 50 個軟件包 | 2.5s | 0.03s | 83 倍更快 |
| 創建虛擬環境 | 0.5s | 0.02s | 25 倍更快 |
工作流對比
傳統工作流（需要 6+ 工具）
# 安裝 Python, 創建 venv, 安裝依賴, 鎖定, 構建...
pyenv install 3.11.0
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip-compile requirements.in -o requirements.txt
python -m build
現代 uv 工作流（1 個工具）
# 一個工具搞定所有事
uv init myproject --python 3.11.0
uv add requests flask
uv lock
uv build
快速上手
安裝方式
| 平台 | 命令 |
|---|---|
| macOS / Linux | `curl -LsSf https://astral.sh/uv/install.sh |
| Windows | `powershell -c "irm https://astral.sh/uv/install.ps1 |
| Homebrew | brew install uv |
pip 命令替換表
| pip 命令 | uv 等效命令 |
|---|---|
pip install package | uv pip install package |
pip install -r reqs.txt | uv pip install -r reqs.txt |
python -m venv .venv | uv venv |
pip list | uv pip list |
pip freeze | uv pip freeze |
現代項目管理
項目初始化
使用 uv init 快速創建具有標準化結構的新 Python 項目：
# 基礎用法：在當前目錄初始化
uv init
# 創建新的項目目錄
uv init myproject
# 指定 Python 版本
uv init --python 3.11
# 創建應用程序（非庫）
uv init --app myapp
# 包含 README 文件
uv init --readme myproject
# 創建不帶虛擬環境的項目
uv init --no-venv myproject
生成的項目結構：
myproject/
├── pyproject.toml # 項目元數據和依賴項
├── uv.lock # 通用鎖定文件 (提交至 Git)
├── .python-version # Python 版本規範
├── README.md # 項目說明（可選）
└── src/
└── myproject/
└── __init__.py # 包初始化
uv init 生成的 pyproject.toml 文件遵循 PEP 621 標準。如需了解各字段的詳細說明和配置最佳實踐，請參閱 pyproject.toml 完整指南。
項目結構
myproject/
├── pyproject.toml # 項目元數據和依賴項
├── uv.lock # 通用鎖定文件 (提交至 Git)
├── .python-version # Python 版本規範
├── src/ # 源代碼
└── tests/ # 測試文件
依賴項管理
- 添加依賴項：
uv add requests - 添加開發依賴項：
uv add --dev pytest - 同步環境：
uv sync（確保.venv與uv.lock一致） - 運行命令：
uv run python main.py（自動處理 venv）
最佳實踐
始終將 uv.lock 提交到你的存儲庫。它能確保每個團隊成員和 CI 環境使用完全相同的依賴項版本。
進階功能
腳本支持
運行帶有內聯依賴項元數據的獨立腳本：
# /// script
# dependencies = ["requests", "rich"]
# ///
import requests
from rich import print
print(requests.get("https://api.github.com").status_code)
運行命令：uv run script.py
工具管理
全局安裝和運行 Python CLI 工具，而不會污染系統 Python：
uv tool install ruff
uvx ruff check . # 無需永久安裝即可運行
Python 管理
uv python install 3.11 3.12 # 安裝特定版本
uv python list # 列出已安裝版本
CI/CD 集成
GitHub Actions
- uses: astral-sh/setup-uv@v3
- run: uv sync
- run: uv run pytest
Docker
FROM python:3.11-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev
與第三方包管理器整合
某些生態系統（如 OpenMMLab）使用自己的包管理器。uv 負責虛擬環境，這些工具管理各自的包。
工作流程
# 1. 用 uv 創建 venv
uv venv .venv
source .venv/bin/activate
# 2. 通過 uv 安裝第三方包管理器
uv pip install openmim
# 3. 用該管理器安裝生態內的包
mim install mmdet mmdet3d mmyolo
核心原則
uv 管理環境和 pip 操作；第三方管理器處理其自有的包版本。只要在運行管理器前啟動 venv，包就會安裝到正確位置。
避免環境混淆
如果未啟動 venv，mim install 可能不會使用正確的 pip。使用以下模式之一：
# 鏈式啟動和安裝
source .venv/bin/activate && mim install mmdet
# 或通過 venv 的 Python 直接調用 mim
.venv/bin/python -m mim install mmdet
# 或使用 uv run
uv pip install openmim && uv run mim install mmdet
使用 uv run 時，環境會自動正確配置：
uv run mim install mmdet # uv 自動處理環境
總結與建議
- 採用
uv init：為新項目使用項目管理功能。 - 使用
uv run：停止手動啟動虛擬環境。 - 提交
uv.lock：確保所有環境的可復現性。 - 使用
uv tool：替代pipx管理全局 CLI 工具。