Python 打包工具 uv 详解：下一代包管理器与构建器

发表于2025-05-12|Python项目构建

|总字数:3.7k|阅读时长:13分钟

uv 是由 Astral 公司开发的一款高性能 Rust 实现的 Python 包安装器和解析器，旨在全面替代 pip、pip-tools 和 virtualenv。它以其惊人的速度、严谨的兼容性和现代化功能，正迅速成为 Python 生态系统中的一个重要工具。

核心思想：提供一个单一、快速且可靠的命令行工具，覆盖 Python 包管理生命周期中的关键操作，从环境创建到依赖解析、安装和锁定。

一、引言：为什么需要 `uv`？

Python 包管理长期以来面临着一些挑战，尤其是在性能和一致性方面：

pip 的局限性：
- 速度慢：pip 在解析大型项目或复杂依赖树时速度较慢，因为它每次都会重新计算依赖，且在网络请求和磁盘 I/O 方面未高度优化。
- 依赖解析不确定性：pip 的解析器有时会出现非确定性行为，对于复杂的依赖冲突，不一定能给出最佳或唯一的解决方案。
- 缺乏锁定文件机制：pip 本身没有内置的锁定文件（requirements.txt 固然可以锁定，但不是通过 pip 自身的解析冲突机制而来）生成能力，需要 pip-tools 等额外工具。
virtualenv 的传统：
- 创建和激活虚拟环境是 Python 开发的基础，但 virtualenv 或 venv 虽实用但在性能上仍有提升空间。
生态系统碎片化：
- 开发者经常需要结合使用 pip (安装)、pip-tools (依赖锁定)、virtualenv (环境管理) 才能获得完整的包管理体验，这增加了工具链的复杂性。
- Poetry、PDM 等工具虽解决了这些问题，但有时对现有工作流引入了较大理念变更。

uv 旨在通过一个单一的二进制文件解决上述痛点，提供一个极速、可靠、兼容的替代方案，并遵循现有的 Python 标准（PEP 517, PEP 660, PEP 582 等）。

二、`uv` 的核心特性

uv 的设计理念和技术实现使其具备以下突出特点：

极致的性能：
- 使用 Rust 编写，能够充分利用现代 CPU 的多核优势，实现并行下载、构建和安装，打包解析速度比 pip 快 8-10 倍，对锁定文件的解析速度更是快了 100 倍以上。
- 通过智能缓存和高效算法，大幅减少了网络请求和磁盘操作。
pip 和 pip-tools 的全面替代：
- 完全兼容标准的 pyproject.toml ([project] 和 [project.optional-dependencies]) 和 requirements.txt 文件格式。
- 提供了 install, uninstall, freeze, list 等 pip 命令的等效功能，以及 compile, sync 等 pip-tools 命令的等效功能。
virtualenv 的高效替代：
- 内置了创建和管理虚拟环境的功能，并且速度极快。
精确且严格的依赖解析：
- uv 的依赖解析器是完全确定性且严格的，它能确保在给定条件下总是找到一个唯一且可行的依赖解决方案。
- 支持 PEP 508 URL 格式、本地路径以及 Git 仓库作为依赖来源。
安全和一致性：
- 支持 pyproject.toml 中的 [build-system] 构建元数据，正确处理 sdist 和 wheel 包。
- 支持对锁定文件中的包进行哈希校验，增强安全性并确保构建的可重复性。
Monorepo 友好：
- uv 的设计考虑了在大型单体仓库 (Monorepo) 中的使用，支持多项目和灵活的依赖管理。

三、安装 `uv`

uv 是一个独立的二进制文件，可以通过多种方式安装：

3.1 使用 `pipx` (推荐)

pipx 是一个用于安装和运行 Python 应用程序的工具，它将 uv 安装在一个独立的虚拟环境中，避免与系统 Python 环境冲突。

1
2
3

pip install pipx
pipx ensurepath
pipx install uv

3.2 使用 `curl` (跨平台)

直接下载并安装 uv 的发布版本：

1	curl -LsSf https://astral.sh/uv/install.sh \| sh

此脚本会将 uv 安装在默认路径（通常是 ~/.cargo/bin/ 或 ~/.local/bin/）并确保将其添加到 PATH。

3.3 手动下载二进制文件

可以从 uv 的 GitHub Release 页面下载对应操作系统的预编译二进制文件，然后将其添加到系统的 PATH 环境变量中。

验证安装：

安装完成后，运行以下命令验证 uv 是否可用：

1	uv --version

四、`uv` 核心指令详解

uv 提供了一套简洁而强大的命令行接口，覆盖了包管理的各个方面。

4.1 环境管理：`uv venv`

uv venv 用于创建和管理 Python 虚拟环境。它替代了 python -m venv 或 virtualenv。

    graph TD
    A[uv venv] --> B{指定Python解释器?}
    B -- Yes --> C[--python <path_or_version>]
    B -- No (使用默认) --> D[在当前目录创建 .venv]
    C --> D
    D --> E{需要预装常用包?}
    E -- Yes --> F[--seed]
    E -- No --> G[完成 Venv 创建]
    F --> G

4.1.1 创建虚拟环境

在当前目录下创建一个名为 .venv 的虚拟环境：

uv venv

激活虚拟环境：

1 2	source .venv/bin/activate # macOS/Linux .venv\Scripts\activate # Windows

4.1.2 指定 Python 解释器

可以通过 --python 参数指定要使用的 Python 解释器的路径或版本。

指定版本（uv 会查找系统中匹配该版本的解释器）：

1	uv venv --python 3.11 # 创建一个使用 Python 3.11 的虚拟环境

指定解释器路径：

1	uv venv --python /usr/bin/python3.10 # 使用特定路径的解释器

4.1.3 预装常用包 (Seeding)

使用 --seed 选项可以预装 pip 和 setuptools 到新的虚拟环境中。这在某些情况下可能有用，尽管 uv 本身通常不需要这些即可工作。

1	uv venv --seed

4.2 包安装与卸载：`uv pip install` / `uv pip uninstall`

uv 的 pip 子命令系列旨在全面替代 pip。

4.2.1 安装单个或多个包

# 安装一个包
uv pip install requests

# 安装多个包
uv pip install flask sqlalchemy

4.2.2 从 `requirements.txt` 文件安装

这通常是生产环境中最常用的方式，确保所有依赖都安装到特定版本。

1	uv pip install -r requirements.txt

4.2.3 可编辑安装 (Editable Install)

对于本地开发的项目，可以使用 . 或路径进行可编辑安装，这样对源代码的修改会立即生效，无需重新安装。

# 在当前目录下可编辑安装项目
uv pip install -e .

# 可编辑安装指定路径的项目
uv pip install -e ../my-local-package

4.2.4 从 `pyproject.toml` 安装

当 pyproject.toml 中定义了 [project] 和 [project.dependencies] 时，可以直接安装项目及其核心依赖。

1	uv pip install .

也可以带上可选依赖 (extras)：

1	uv pip install ".[dev,test]" # 安装 main 依赖和 dev、test 可选依赖

4.2.5 卸载包

# 卸载一个包
uv pip uninstall requests

# 卸载多个包
uv pip uninstall flask sqlalchemy

4.3 包查询：`uv pip freeze` / `uv pip list`

4.3.1 `uv pip freeze` (生成锁定文件)

列出虚拟环境中所有已安装的顶层包及其精确版本，格式兼容 requirements.txt。这通常用于生成项目的 requirements.txt 锁定文件。

1	uv pip freeze > requirements.txt

注意：uv pip freeze 和 uv pip compile 功能有所重叠。在需要严格锁定子依赖时，uv pip compile 更加强大和推荐。

4.3.2 `uv pip list` (详细列表)

列出所有已安装的包，通常包括包的版本和路径。

1	uv pip list

4.4 依赖解析与锁定：`uv pip compile`

uv pip compile 是 uv 的核心功能之一，它致力于替代 pip-tools compile，通过解析 pyproject.toml 或 requirements.in 文件来生成精确的锁定文件（如 requirements.txt）。

    graph TD
    A[uv pip compile] --> B{输入文件?}
    B -- pyproject.toml --> C["解析 [project.dependencies] 和 [project.optional-dependencies]"]
    B -- requirements.in --> D[解析 requirements.in]
    C --> E[解析所有依赖树]
    D --> E
    E --> F{生成哈希?}
    F -- Yes --> G[--generate-hashes]
    F -- No --> H[生成锁定文件]
    G --> H
    H --> I[输出到 <file>]
    I --> J["完成 (如 requirements.txt)"]

4.4.1 从 `pyproject.toml` 生成锁定文件

假设你的 pyproject.toml 包含：

# pyproject.toml
[project]
name = "my-project"
version = "0.1.0"
dependencies = [
    "flask",
    "SQLAlchemy",
]

[project.optional-dependencies]
dev = [
    "pytest",
    "black",
]

生成所有核心依赖的锁定文件：

1	uv pip compile pyproject.toml --output requirements.txt

生成包含开发依赖的锁定文件：

1
2
3

uv pip compile pyproject.toml --extra dev --output requirements-dev.txt
# 或者更简洁地通过路径和 extras 指定
uv pip compile ".[dev]" --output requirements-dev.txt

4.4.2 从 `requirements.in` 生成锁定文件

如果你仍然习惯使用 requirements.in 文件来声明顶层依赖：

1
2
3

# requirements.in
flask
sqlalchemy>=1.4

然后编译生成 requirements.txt：

1	uv pip compile requirements.in --output requirements.txt

4.4.3 生成带哈希校验的锁定文件

为了增强安全性并确保包的完整性，uv 可以为每个包生成哈希值。在安装时，uv 会校验这些哈希值。

1 2	# 生成 requirements.txt，并为所有包添加 sha256 哈希 uv pip compile pyproject.toml --generate-hashes --output requirements.txt

生成的文件内容示例：

# This file is autogenerated by uv (version 0.1.28)
#
# To update, run:
#
#    uv pip compile pyproject.toml -o requirements.txt
#
aiohttp==3.9.5 \
    --hash sha256:7b5e4c02f741b0b5e9f8d0a8b9e6f3d0c1e4f9b8a0d7c6e5f4a3b2c1d0e9f8a \
    --hash sha256:7c6f5e4d3c2b1a0f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b7a6
# ... 其他包

性能优势：对于复杂的依赖图，uv pip compile 的速度相较于 pip-tools compile 有数量级的提升。

4.5 从锁定文件同步环境：`uv pip sync`

uv pip sync 用于根据一个或多个锁定文件（通常是 requirements.txt）来安装或更新虚拟环境中的包，确保环境与锁定文件精确匹配。它会智能地添加、更新或删除包，以达到所需状态。

1 2	# 根据 requirements.txt 同步虚拟环境 uv pip sync requirements.txt

同步多个锁定文件：

1	uv pip sync requirements.txt requirements-dev.txt

这对于确保所有开发者和部署环境都拥有完全相同的依赖集至关重要。

4.6 在虚拟环境中运行命令：`uv run`

uv run 允许你在当前激活的虚拟环境 (或 uv 识别到的 .venv 目录) 中执行命令，而无需手动激活环境。

# 在当前虚拟环境中运行 Python 脚本
uv run python my_script.py

# 运行 pytest
uv run pytest tests/

这在自动化脚本或 CI/CD 流水线中非常有用，可以确保命令在正确的环境中执行。

4.7 `pyproject.toml` 项目依赖管理：`uv project`

uv project 系列命令提供了直接操作 pyproject.toml 文件中项目依赖的能力，类似于 Poetry add/remove。

它要求当前目录或父目录存在 pyproject.toml 文件。

4.7.1 添加项目依赖

# 添加一个运行时依赖
uv project add rich

# 添加一个开发依赖
uv project add ruff --dev

# 添加一个带有特定版本的依赖
uv project add "pydantic==2.0.0"

这会自动修改 pyproject.toml 中的 [project.dependencies] 或 [project.optional-dependencies] 部分。

4.7.2 移除项目依赖

# 移除一个运行时依赖
uv project remove rich

# 移除一个开发依赖
uv project remove ruff --dev

这会自动修改 pyproject.toml。

4.7.3 同步项目依赖

uv project sync 会根据 pyproject.toml 中的 [project.dependencies] 和 [project.optional-dependencies] 来解析、安装和同步虚拟环境中的包。它结合了 uv pip compile 和 uv pip sync 的功能。

# 同步核心依赖
uv project sync

# 同步核心依赖和开发依赖
uv project sync --dev

工作流示例：

uv venv (创建环境)
uv project add ruff (添加依赖到 pyproject.toml)
uv project sync (解析并安装依赖到环境)

4.8 缓存管理：`uv cache`

uv 会在本地维护一个缓存，存储下载的包文件和解析结果，以加速后续操作。uv cache 命令用于管理这个缓存。

4.8.1 查看缓存目录

1	uv cache dir

这会显示 uv 存储其缓存的路径。

4.8.2 清理缓存

1	uv cache clean

此命令会删除 uv 的所有缓存数据，强制 uv 在下次运行时重新下载和解析。这在遇到缓存问题或需要释放磁盘空间时很有用。

五、`uv` 与 Python 生态系统

uv 的目标是成为 Python 包管理的底层基石。

与现有工具链兼容：uv 很好地替代了 pip、pip-tools、virtualenv。这意味着你可以逐步将现有项目迁移到 uv，而无需彻底改变 {pyproject.toml, requirements.in, requirements.txt} 这样的惯用文件。
与其他项目管理工具的集成：虽然 uv 提供了 project 命令来简化 pyproject.toml 的管理，但它本身并不是一个完整的项目管理工具（如 Poetry, Rye, Hatch, PDM）。这些工具通常包含额外的功能，如发布、插件管理、脚本运行等。
- uv 可以在这些工具的底层作为包安装和解析的核心引擎。例如，Rye 已经集成了 uv 作为其默认的包解析器和安装器。
- 对于那些不希望引入 Poetry 等工具的复杂性，或者追求极致性能的项目，uv 是一个优秀的独立包管理解决方案。

六、安全性考虑

uv 在设计时就考虑了安全性：

哈希校验：uv pip compile --generate-hashes 可以在锁定文件中包含包的哈希值，确保在安装时下载的包与预期一致，防止中间人攻击或篡改。
严格解析：其确定性解析器减少了模糊性，降低了意外安装不兼容或恶意包的风险。
隔离环境：通过 uv venv 创建虚拟环境，保持项目依赖的隔离性，避免系统级冲突。

像所有包管理器一样，依然建议：

始终从信誉良好的包源（如 PyPI）下载包。
定期审查 requirements.txt 或 pyproject.toml 中的依赖。
使用 uv 时保持其自身的更新，以获取最新的安全修复和功能。

七、总结

uv 的出现标志着 Python 包管理领域的一个重要进步。它以前所未有的速度、严谨的兼容性和精简的单一二进制文件，解决了 Python 开发者长期以来在依赖解析、包安装和环境管理方面的痛点。

无论你是小型项目的独立开发者，还是大型机构的团队成员，uv 都提供了一个强大且高效的工具，来提升开发体验和确保项目依赖的一致性。对于追求高性能和简单性的项目，uv 无疑是一个值得尝试和采纳的现代化解决方案。随着其功能的不断完善，uv 有望成为 Python 生态系统中的新一代标准包管理工具。

文章作者: TeaTang

文章链接: https://blog.tbf1211.xx.kg/62acbead38d8/