🚀 Python 打包工具 UV 使用指南

UV 是一個用 Rust 編寫的極速 Python 包管理器和解析器，旨在成為 pip、pip-tools、virtualenv 等工具的單一替代方案。

📋 目錄

1. 核心概念與設計哲學
2. 安裝與配置
3. 基礎使用方法
4. 項目管理與工作流
5. 高級功能與技巧
6. 與其他工具集成
7. 性能優化與最佳實踐
8. 故障排除與調試
9. 學習資源與進階

🧠 核心概念與設計哲學

設計目標

• 極速性能: 比傳統工具快 10-100 倍
• 一體化解決方案: 替代 pip、pip-tools、virtualenv、pipenv 等
• 現代標準支持: 優先支持 pyproject.toml 和 PEP 標準
• 可靠性: 基于 Rust 的內存安全性和強大的依賴解析器

核心組件

• 包安裝器: 替代 pip 的功能
• 虛擬環境管理器: 替代 virtualenv 的功能
• 依賴解析器: 基于 PubGrub 算法的高效解析
• 項目初始化器: 創建新項目結構

🔧 安裝與配置

多種安裝方式

# Windows PowerShell (推薦)
powershell -ExecutionPolicy Bypass -c "irm https://astral.sh/uv/install.ps1 | iex"# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh# 使用 pip (已安裝Python的情況下)
pip install uv# 使用 pipx
pipx install uv# 使用 Homebrew (macOS)
brew install uv# 手動安裝 (從發布頁面下載)
# 訪問: https://github.com/astral-sh/uv/releases

配置設置

# 查看所有配置選項
uv config list# 設置全局Python版本
uv config set default-python-version 3.11# 配置鏡像源 (國內用戶推薦)
uv config set index-url https://pypi.tuna.tsinghua.edu.cn/simple/# 或者通過環境變量
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple/

配置文件位置

• 全局配置: ~/.config/uv/uv.toml (Linux/macOS) 或 %APPDATA%\uv\uv.toml (Windows)
• 項目級配置: 項目目錄中的 uv.toml

📖 基礎使用方法

虛擬環境管理

# 創建虛擬環境
uv venv .venv# 創建指定Python版本的虛擬環境
uv venv --python 3.11 .venv# 激活虛擬環境 (Windows)
.\.venv\Scripts\activate# 激活虛擬環境 (Unix/macOS)
source .venv/bin/activate# 列出可用Python版本
uv python list# 安裝特定Python版本
uv python install 3.11

包管理操作

# 安裝單個包
uv pip install requests# 安裝多個包
uv pip install requests pandas numpy# 安裝指定版本的包
uv pip install "django==4.2.0"# 從requirements.txt安裝
uv pip install -r requirements.txt# 列出已安裝的包
uv pip list# 卸載包
uv pip uninstall package-name# 更新包
uv pip install --upgrade package-name# 查看包信息
uv pip show package-name

依賴管理

# 生成requirements.txt
uv pip freeze > requirements.txt# 安裝開發依賴
uv pip install --dev black isort flake8# 根據pyproject.toml安裝依賴
uv pip install -e .

🏗? 項目管理與工作流

項目初始化與設置

# 創建新項目
uv init my-project
cd my-project# 添加生產依賴
uv add requests# 添加開發依賴
uv add --dev black# 安裝所有依賴 (根據pyproject.toml)
uv sync# 安裝生產依賴 only
uv sync --production# 更新依賴鎖文件
uv sync --upgrade

依賴解析與鎖文件

# 檢查依賴更新
uv pip list --outdated# 更新所有依賴
uv pip install --upgrade --all# 生成精確的鎖文件
uv sync --locked# 驗證當前依賴與鎖文件一致性
uv sync --check

項目結構示例

my-project/
├── pyproject.toml    # 項目配置和依賴聲明
├── uv.lock           # 依賴鎖文件 (自動生成)
├── src/
│   └── my_project/
│       ├── __init__.py
│       └── module.py
├── tests/
│   └── test_module.py
└── .venv/            # 虛擬環境 (可選)

🚀 高級功能與技巧

緩存與性能優化

# 清理緩存
uv cache clean# 查看緩存信息
uv cache info# 預下載包到緩存 (用于CI環境)
uv pip download --only-binary=:all: --dest ./cache-dir -r requirements.txt

平臺特定依賴

# 在pyproject.toml中指定平臺特定依賴
[project]
dependencies = ["requests","cffi; platform_machine == 'x86_64'",
]# 或者使用環境標記
[project.optional-dependencies]
windows = ["pywin32"]
linux = ["dbus-python"]

自定義索引源

# 添加額外包索引源
uv config set extra-index-urls '["https://pypi.company.com/simple"]'# 或使用TOML配置
[[index]]
url = "https://pypi.company.com/simple/"
name = "company"
priority = 1

二進制包控制

# 強制使用源碼編譯
uv pip install --no-binary :all: package-name# 強制使用預編譯二進制包
uv pip install --only-binary :all: package-name# 指定特定包的二進制策略
uv pip install --only-binary=:numpy: --no-binary=:pandas: .

🔗 與其他工具集成

與PDM/Poetry項目兼容

# 安裝PDM項目
uv pip install -e . --no-deps
uv sync --dev# 安裝Poetry項目
uv pip install -e .
uv sync --dev --extras all

CI/CD集成示例

# GitHub Actions 示例
name: CIon: [push, pull_request]jobs:test:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v4- uses: astral-sh/setup-uv@v3with:python-version: "3.11"- run: uv sync --dev- run: uv run pytest

預發布環境配置

# 安裝預發布版本
uv pip install --pre package-name# 允許安裝alpha/beta版本
uv pip install --upgrade --pre package-name

? 性能優化與最佳實踐

最佳實踐指南

1. 利用緩存機制: UV 具有高效的緩存系統，避免重復下載
2. 使用鎖文件: 始終使用 uv.lock 確保環境一致性
3. 合理配置鏡像源: 國內用戶配置國內鏡像大幅提升速度
4. 按需安裝二進制包: 根據需要選擇源碼編譯或預編譯二進制包

性能對比技巧

# 對比UV和pip的性能
time uv pip install -r requirements.txt
time pip install -r requirements.txt# 清除緩存后測試
uv cache clean
pip cache purge

大型項目優化

# 分階段安裝依賴 (Dockerfile中特別有用)
# 第一階段: 安裝構建依賴
uv sync --dev --production# 第二階段: 僅安裝運行依賴
uv sync --production

🐛 故障排除與調試

常見問題解決

# 詳細日志輸出
uv pip install -v package-name# 更詳細的調試信息
uv pip install -vv package-name# 顯示依賴解析樹
uv pip install --dry-run --report - > report.json# 檢查環境問題
uv debug --verbose

依賴沖突解決

# 查看依賴沖突信息
uv pip check# 強制重新安裝所有依賴
uv pip install --force-reinstall -r requirements.txt# 忽略已安裝的包
uv pip install --ignore-installed package-name

網絡問題處理

# 設置超時時間
uv pip install --timeout 60 package-name# 設置重試次數
uv pip install --retries 3 package-name# 使用代理
export UV_HTTP_PROXY=http://proxy.example.com:8080
export UV_HTTPS_PROXY=http://proxy.example.com:8080

📚 學習資源與進階

官方資源

• 官方文檔
• GitHub 倉庫
• Discord 社區

進階主題

1. 自定義解析策略: 學習如何配置依賴解析行為
2. 插件開發: 了解如何為 UV 開發擴展功能
3. 源碼編譯: 從源碼編譯 UV 以獲得最新特性
4. 集成測試: 在復雜項目中實施 UV 的測試策略

遷移指南

# 從 requirements.txt 遷移到 pyproject.toml
uv init
uv add -r requirements.txt# 從 Pipenv 遷移
uv pip install -r Pipfile --dev# 從 Poetry 遷移
uv pip install -r pyproject.toml --dev