🚀 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