Python使用UV指南
# Python UV 包管理工具指南
# 目录
# 简介
UV是一个由Astral（Ruff的创建者）开发的极速Python包管理工具，使用Rust语言编写。它旨在成为一个统一的工具，可以替代pip、pip-tools、pipx、poetry、pyenv、virtualenv等多种Python工具，提供更快的性能和更好的用户体验。
UV的设计理念是简化Python项目的依赖管理，同时提供卓越的性能。在基准测试中，UV比传统工具快10-100倍，特别是在热缓存环境下，性能提升更为显著。
# 主要特点
- 极速性能：比传统工具（如pip、poetry）快8-115倍
- 统一工具链：替代多种Python工具（pip、pip-tools、pipx、poetry、pyenv、virtualenv等）
- 高效的磁盘空间利用：通过全局缓存实现依赖项去重
- 灵活安装：无需Rust或Python即可通过curl或pip安装
- 跨平台支持：完全兼容macOS、Linux和Windows
- 高级依赖管理：支持依赖版本覆盖、替代解析策略和冲突跟踪解析器
- 清晰的错误消息：一流的错误处理确保开发人员能够高效解决冲突
- 现代Python特性支持：支持可编辑安装、Git依赖、直接URL、本地依赖、约束文件等
- 应用和脚本管理：安装和管理Python版本，运行带有内联依赖元数据的脚本
- 通用锁文件：简化项目管理，提供一致且可移植的锁文件
- 工作区支持：通过类似Cargo的工作区管理处理可扩展项目
# 安装方法
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
推荐这种方式，pip方式的安装会污染环境。默认安装到C:\Users\Administrator\.local\bin，将其添加到环境变量。
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# 通过pip安装
pip install uv
# 通过pipx安装
pipx install uv
# 基本用法
# 创建虚拟环境
UV可以创建和管理Python虚拟环境，速度比传统工具快得多：
# 创建虚拟环境
uv venv env_name
# 使用特定Python版本创建虚拟环境
uv venv --python=3.12 env_name
2
3
4
5
# 激活虚拟环境
source env_name/bin/activate # Linux/macOS
env_name\Scripts\activate # Windows
2
# 管理依赖
UV提供了简单而强大的依赖管理功能：
# 初始化新项目
uv init my_project
cd my_project
# 添加依赖
uv add fastapi
# 添加开发依赖
uv add --group dev pytest ruff
# 运行项目
uv run python main.py
2
3
4
5
6
7
8
9
10
11
12
# 运行脚本
UV可以管理单文件脚本的依赖和环境：
# 创建脚本并添加内联元数据声明其依赖项
echo 'import requests; print(requests.get("https://astral.sh"))' > example.py
# 为脚本添加依赖
uv add --script example.py requests
# 在隔离的虚拟环境中运行脚本
uv run example.py
2
3
4
5
6
7
8
# 高级功能
# Python版本管理
UV可以安装和管理多个Python版本：
# 安装多个Python版本
uv python install 3.10 3.11 3.12
# 查看已安装的Python版本
uv python list
# 在当前目录中使用特定Python版本
uv python pin 3.11
2
3
4
5
6
7
8
# 依赖锁定
UV支持依赖锁定，确保环境的一致性：
# 创建锁文件
uv lock
# 根据锁文件同步环境
uv sync
# 升级特定包
uv lock --upgrade-package requests
# 升级所有包
uv lock --upgrade
2
3
4
5
6
7
8
9
10
11
# 工作区支持
UV支持类似Cargo的工作区，适用于可扩展项目：
# 在工作区中添加依赖
uv add --workspace fastapi
2
# 工具运行
UV可以执行和安装Python包提供的命令行工具，类似于pipx：
# 在临时环境中运行工具
uvx pycowsay 'hello world!'
# 安装工具
uv tool install ruff
2
3
4
5
# 与其他工具比较
# UV vs Pip
| 特性 | UV | Pip |
|---|---|---|
| 速度 | 极快（8-115倍于pip） | 较慢 |
| 依赖解析 | 高级冲突跟踪 | 基本解析 |
| 缓存策略 | 全局缓存，高效利用磁盘空间 | 基本缓存 |
| 虚拟环境 | 内置支持 | 需要venv或virtualenv |
| 锁文件 | 原生支持 | 需要pip-tools |
| Python版本管理 | 内置支持 | 不支持 |
# UV vs Poetry
| 特性 | UV | Poetry |
|---|---|---|
| 速度 | 极快（10倍于Poetry） | 较快（但比UV慢） |
| 实现语言 | Rust | Python |
| 资源占用 | 轻量级 | 中等 |
| 依赖组 | 支持 | 支持 |
| 项目发布 | 支持 | 支持 |
| 工具链集成 | 更广泛（替代多种工具） | 中等 |
# UV vs Conda
| 特性 | UV | Conda |
|---|---|---|
| 速度 | 极快（30倍于Conda） | 慢 |
| 非Python包 | 不支持 | 支持 |
| 环境隔离 | 项目级虚拟环境 | 全局环境管理 |
| 资源占用 | 轻量级 | 重量级 |
| 适用场景 | 纯Python项目 | 数据科学、混合语言项目 |
# 最佳实践
使用UV的pip接口进行迁移：如果你已经有使用pip的项目，可以通过UV的pip接口（
uv pip）无缝迁移，享受性能提升。利用依赖组：使用依赖组（如dev、test、prod）来组织不同环境的依赖。
结合使用锁文件：始终使用锁文件（
uv.lock）确保环境的一致性和可重现性。脚本内联依赖：对于单文件脚本，使用内联依赖元数据简化依赖管理。
CI/CD优化：在CI/CD环境中，使用UV可以显著提高构建速度。
# 常见问题
问题：UV与现有的pip requirements.txt文件兼容吗？
回答：是的，UV完全兼容现有的pip requirements.txt文件，可以使用uv pip install -r requirements.txt直接导入它们。
问题：如何从Poetry迁移到UV？
回答：UV可以直接使用Poetry的pyproject.toml文件，使迁移过程非常简单。你可以继续使用现有的项目结构，只需开始使用UV命令。
问题：UV是否支持私有PyPI仓库？
回答：是的，UV支持自定义索引和私有PyPI仓库，与pip的行为类似。
问题：UV是否支持editable安装？
回答：是的，UV支持可编辑安装（editable installs），适用于开发中的包。