UV：下一代Python包管理工具的全面指南

Python（Photo by Emile Perron on Unsplash) ）

目录

• 目录
• 1. UV 介绍
  • 1.1 什么是UV？
  • 1.2 UV的核心优势
  • 1.3 UV和其他工具对比
• 2. UV的安装与常用命令
  • 2.1 安装UV
  • 2.2 创建和管理项目
  • 2.3 依赖管理命令
  • 2.4 使用工具
• 3 内部原理
  • 3.1 依赖解析器
  • 3.2 分叉解析
  • 3.3 Python 版本兼容性
  • 3.4 性能优化
• 4 速查表
  • 4.1 环境管理
  • 4.2 包管理
  • 4.3 项目管理
  • 4.4 工具管理
• 参考资料

1. UV 介绍

UV 是一个由 Astral 公司用 Rust 开发的高性能 Python 包管理工具，旨在提供比传统 pip 更快的包安装和依赖管理体验。

An extremely fast Python package and project manager, written in Rust.

Python 生态系统中的包管理一直是开发者关注的焦点。从最初的 pip 到后来的 Poetry、PDM 等工具，每一次演进都试图解决前代工具的痛点。而今天我们要介绍的 UV，作为由 Ruff 团队（Astral）开发的下一代 Python 包管理工具，正以其惊人的速度和创新的设计理念，重新定义 Python 包管理的标准。

1.1 什么是UV？

UV 是一个极速的 Python 包管理器和解析器，由 Rust 编写，专注于提供卓越的性能和用户体验。其名称 "UV" 源自 "μv"（微伏），暗示着其轻量级和高效的特性。作为 pip 的直接替代品，UV 提供了兼容的命令行接口，同时在速度上实现了数量级的提升。

1.2 UV的核心优势

与传统的 Python 包管理工具相比，UV 具有以下显著优势：

• 🚀 一体化工具：一个工具替代 pip、pip-tools、pipx、poetry、pyenv、twine、virtualenv 等多种工具
• ⚡️ 极致速度：比 pip 快 10-100 倍
• 🗂️ 全面项目管理：提供通用锁文件的综合项目管理功能
• ❇️ 脚本运行：支持带有内联依赖元数据的脚本运行
• 🐍 Python版本管理：安装和管理不同的 Python 版本
• 🛠️ 工具安装：运行和安装以 Python 包形式发布的工具
• 🔩 兼容pip接口：提供熟悉的命令行界面，同时大幅提升性能
• 🏢 工作区支持：支持 Cargo 风格的工作区，适用于大规模项目
• 💾 高效磁盘空间利用：通过全局缓存实现依赖去重
• ⏬ 简易安装：无需 Rust 或 Python 环境，可通过 curl 或 pip 直接安装
• 🖥️ 多平台支持：支持 macOS、Linux 和 Windows 系统

随着Python项目规模和复杂度的增长，传统工具在性能和用户体验方面的局限性日益凸显。UV 的出现，为开发者提供了一个更快、更可靠的选择，特别适合大型项目和CI/CD环境中的应用。

1.3 UV和其他工具对比

在Python生态系统中，包管理和环境管理工具众多，主要包括pip+virtualenv、Poetry、Conda等。在决定是否采用UV之前，了解它与现有工具的区别和优势非常重要。

UV vs. pip+virtualenv

pip和virtualenv是Python包管理和虚拟环境创建的传统工具组合。UV相比它们具有以下优势：

• 速度：UV的Rust实现使其比pip快10-100倍，特别是在大型项目中
• 集成环境管理：UV将包管理和环境管理集成在一个工具中，简化了工作流程
• 内存使用：UV在包安装和依赖解析过程中使用的内存显著减少
• 错误处理：UV提供更清晰的错误信息和更好的依赖冲突解决方案
• 可复现性：UV的锁文件方法确保了跨系统环境的一致性，这是基本requirements.txt文件无法保证的

UV vs. Conda

Conda是一个完整的包管理解决方案，特别适合科学计算环境。UV与Conda相比：

• 速度：UV的包安装和依赖解析速度远快于Conda的有时缓慢的性能
• 资源占用：UV具有更小的资源占用，意味着更少的内存使用和更快的启动时间
• 集成性：UV与现有Python打包标准和工具无缝集成，更容易与更广泛的Python生态系统协作
• 非Python包：Conda可以管理非Python包和系统级依赖，而UV专注于Python包

UV vs. Poetry

Poetry是另一个现代Python项目管理工具，与UV有许多相似之处：

• 依赖管理：两者都有效处理包依赖和虚拟环境
• 项目结构：两者都提供初始化和构建Python项目的工具
• 锁文件：两者都生成锁文件以确保环境可复现

然而，UV的Rust实现使其在速度和资源使用方面具有显著优势。此外，UV与现有Python包管理工具的兼容性意味着它可以与其他工具（如pip）一起工作，提供了Poetry更固执己见的方法有时缺乏的灵活性。

功能对比表

总的来说，UV结合了现有工具的最佳特性，同时通过其Rust实现提供了显著的性能优势。对于寻求更快、更可靠的Python包管理解决方案的开发者来说，UV是一个极具吸引力的选择，特别是对于大型项目或CI/CD环境。

2. UV的安装与常用命令

2.1 安装UV

UV的安装非常简单，支持多种操作系统和安装方式。以下是几种常见的安装方法：

使用官方安装脚本（推荐）

# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

使用包管理器

# macOS (Homebrew)
brew install uv

安装完成后，可以通过以下命令验证安装是否成功：

uv --version

安装正确会得到版本号：

uv 0.7.11 (90a4416ab 2025-06-04)

2.2 创建和管理项目

UV提供了一套完整的命令用于创建和管理Python项目：

创建新项目

创建新项目

# 创建一个新的Python项目目录
uv init example
# 运行正确会显示：Initialized project `example` at `/路径/example`

有三个默认文件：README.md、main.py、pyproject.toml

# 创建一个新的Python项目目录
uv init example
# Initialized project `example` at `/路径/example`

查看目录内容：

cd example
tree -a -L 1

.
├── .git
├── .gitignore
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

该 main.py 文件包含一个简单的“Hello world”程序。尝试一下uv run main.py

初始化一个新的虚拟环境： uv venv ，正确运行后得到虚拟环境信息

Using CPython 3.13.1
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate

直接运行 main.py 也可以创建虚拟环境

uv run main.py

激活虚拟环境

source .venv/bin/activate

2.3 依赖管理命令

UV 提供了一系列强大的依赖管理命令，以下是最常用的几个：

添加依赖

使用 uv add 命令可以向项目添加依赖。该命令会自动更新 pyproject.toml 文件、锁文件和项目环境：

# 添加单个包
uv add requests

# 指定版本约束
uv add 'requests==2.31.0'

# 添加 Git 依赖
uv add git+https://github.com/psf/requests

# 从 requirements.txt 文件添加所有依赖
uv add -r requirements.txt -c constraints.txt

删除依赖

使用 uv remove 命令可以删除项目依赖：

# 删除包
uv remove requests

升级依赖

使用 uv lock 命令配合 --upgrade-package 参数可以升级指定包：

# 升级特定包
uv lock --upgrade-package requests

该命令会尝试将指定包更新到最新的兼容版本，同时保持锁文件中其他依赖不变。

安装项目依赖

当你有一个包含 pyproject.toml 的项目时，可以使用以下命令安装所有依赖：

# 安装项目依赖
uv pip install -e .

# 安装包含开发依赖
uv pip install -e ".[dev]"

同步项目环境

使用 uv sync 命令可以确保项目环境与锁文件保持同步：

# 同步项目环境
uv sync

运行项目命令

uv run 命令可以在项目环境中运行脚本或命令。在每次运行前，UV 会验证锁文件是否与 pyproject.toml 同步，并确保环境与锁文件一致：

# 运行 Python 脚本
uv run main.py

构建项目分发包

uv build 命令可用于构建项目的源码分发包和二进制分发包（wheel）：

# 构建项目
uv build

# 查看构建结果
ls dist/
# 输出示例：
# Successfully built dist/example-0.1.0.tar.gz
# Successfully built dist/example-0.1.0-py3-none-any.whl

这些命令提供了一个完整的项目依赖管理工作流程，从添加依赖、删除依赖、升级依赖到运行项目和构建分发包。UV 的这些命令设计直观且高效，大大简化了 Python 项目的依赖管理。

2.4 使用工具

UV 提供了强大的工具管理功能，可以替代 pipx 等工具来运行和管理 Python 工具。

运行工具（不安装）

uvx 命令可以在不安装工具的情况下直接运行工具：

# 运行带参数的工具
uvx pycowsay "Hello from UV"
  -------------
< Hello from UV >
  -------------
   \   ^__^
    \  (oo)\_______
       (__)\       )\/\
           ||----w |
           ||     ||

运行 ruff 代码检查工具

# 运行 ruff 代码检查工具
uvx ruff check .
# All checks passed!

uv tool run ruff check .
# All checks passed!

注意：uvx 是 uv tool run 的便捷别名。使用 uvx 运行的工具会在临时的隔离环境中安装和运行。

指定工具版本

可以使用 @ 语法指定工具的版本：

# 运行特定版本的工具
uvx ruff@0.1.5 check .

# 运行最新版本的工具
uvx ruff@latest check .

也可以使用 --from 选项指定更复杂的版本约束：

# 指定版本范围
uvx --from 'ruff>0.2.0,<0.3.0' ruff check .

安装工具

如果经常使用某个工具，可以将其安装到持久环境中，并添加到 PATH 中：

# 安装 ruff 工具
uv tool install ruff

# 安装特定版本的工具
uv tool install 'ruff>=0.3.0'

# 从 Git 仓库安装工具
uv tool install git+https://github.com/astral-sh/ruff

安装工具后，可以直接在命令行中运行该工具，无需通过 UV 调用：

# 直接运行已安装的工具
ruff --version

注意：与 uv pip install 不同，安装工具不会在当前环境中提供其模块。这种隔离对于减少工具、脚本和项目之间的依赖冲突非常重要。

升级工具

使用 uv tool upgrade 命令可以升级已安装的工具：

# 升级特定工具
uv tool upgrade ruff

# 升级所有工具
uv tool upgrade --all

工具升级会尊重安装工具时提供的版本约束。例如，如果使用 uv tool install ruff >=0.3,<0.4 安装了 Ruff，然后运行 uv tool upgrade ruff，则将升级 Ruff 到 >=0.3,<0.4 范围内的最新版本。

使用插件和额外依赖

可以使用 --with 选项添加额外的依赖或插件：

# 运行带插件的工具
uvx --with mkdocs-material mkdocs serve

# 安装带插件的工具
uv tool install mkdocs --with mkdocs-material

使用 --from 选项可以运行带有额外功能的工具：

# 使用额外功能
uvx --from 'mypy[faster-cache,reports]' mypy --xml-report mypy_report

这些命令使 UV 成为一个强大的 Python 工具管理器，可以替代 pipx 和其他类似工具，并且提供了更高的性能和更多的功能。

3 内部原理

UV 的出色性能不仅仅是因为它使用 Rust 语言开发，更在于其内部实现了多种高效的算法和优化策略。下面我们将揭开 UV 的核心技术原理。

3.1 依赖解析器

UV 使用基于 PubGrub 算法的依赖解析器，这是一种增量版本求解器。与传统的 SAT 求解器不同，UV 的解析器具有以下特点：

1. 增量解析：从一个部分解决方案开始，逐步选择包版本，而不是尝试所有可能的组合。

2. 智能优先级：包的选择基于优先级系统，URL 包优先级最高，然后是精确版本说明符，再然后是宽松说明符。

3. 版本偏好：优先使用锁文件和当前环境中的版本，以及最高版本（除非指定其他解析策略）。

4. 预取优化：在后台预取包的元数据，显著提高性能。

5. 智能回溯：当检测到冲突时，解析器会进行回溯，并记录不兼容项，以避免重复尝试无效组合。

6. 有意义的错误报告：当解析失败时，提供清晰的错误跟踪，指出冲突的具体包和版本。

3.2 分叉解析

UV 采用了分叉解析器策略，可以处理不同环境下的矛盾需求：

1. 条件依赖：当包有多个带有不同标记的要求时（如基于 Python 版本或操作系统的条件），解析会被分割。

2. 智能合并：具有相同包的分叉会合并，以保持分叉数量较少。

3. 锁文件稳定性：锁文件中会记录分叉信息，确保解析稳定性。

3.3 Python 版本兼容性

UV 严格处理 Python 版本兼容性，确保所有依赖项都能在指定的 Python 版本上正确安装：

1. 最低版本传播：如果项目要求 Python >= 3.9，那么声明了 Python >= 3.10 的包版本会被拒绝。

2. 版本下限尊重：为了简化和向前兼容，只会尊重 requires-python 中的下限。

3.4 性能优化

UV 的高性能来自于多方面的优化：

1. Rust 实现：使用 Rust 语言开发，具有出色的性能和内存安全性。

2. 并行下载：并行处理包下载和元数据获取。

3. 智能缓存：全局缓存机制避免重复下载和安装相同的包。

4. 最小化磁盘操作：优化的文件操作和磁盘访问模式。

5. 增量处理：在解析和安装过程中采用增量方法，避免不必要的全量重建。

这些内部原理使 UV 能够在保持兼容性的同时，实现比传统工具快 10-100 倍的性能。对于大型项目和复杂依赖关系，这些优化尤为重要。

4 速查表

下面是 UV 工作流程中的常见操作速查表，帮助您快速查找和使用 UV 的各种命令。

4.1 环境管理

4.2 包管理

4.3 项目管理

4.4 工具管理

参考资料

• UV 官方文档
• UV GitHub 仓库
• Astral 官方网站
• Python UV: The Ultimate Guide to the Fastest Python Package Manager
• uv: An In-Depth Guide to Python's Fast and Ambitious New Package Manager
• PEP 517 -- 构建系统规范
• PEP 518 -- pyproject.toml 规范