uv | yuanjing's blog – stories, insights, and ideas

一句话项目 slogan：把 Python 工具链碎成一地的问题，收进一个二进制。

这是「一天一个开源项目」系列的一篇。今天讲 uv。

Python 的包管理工具链是出了名的碎。装包用 pip，锁依赖用 pip-tools，隔离环境用 virtualenv，装命令行工具用 pipx，构包用 build，发包用 twine，管 Python 版本用 pyenv。每个都有独立的版本号、独立的缓存、独立的配置文件、独立的坑。

更麻烦的是它们互相不兼容。pip-tools 锁出来的 requirements.txt，pip 不认；poetry 的 pyproject.toml 格式，pip 也不认。你花时间搞明白一个工具的锁文件怎么和另一个工具的缓存共存，然后下一个项目又是另一套。

uv 的目标是把这一整堆收进一个二进制文件里。

项目速览

⭐ 90,969 Stars ｜ 🍴 3,678 Forks ｜ 📄 Apache-2.0 协议 ｜ 🔧 11,155 次提交 ｜ 🐛 2,984 个 Open Issues

截至 2026-10-21。项目创建于 2023-10-02，不到三年 9 万星。核心作者 charliermarsh 贡献 3,443 次提交，zanieb 2,162 次——这背后是 Astral 这家公司（Ruff 的作者），不是个人玩具。

阅读价值与前置说明

读完你应该能回答：

为什么 uv 放弃了 pip 用了二十年的回溯算法，换成一个 SAT 求解器？
一份 uv.lock 为什么能同时锁住 macOS、Linux、Windows 和多个 Python 版本？
同一个包装进 10 个虚拟环境，磁盘上真的只有一份吗？
一个二进制文件怎么同时塞进包管理、项目管理、Python 版本管理和构建后端？

前置知识：

了解 Python 基础（虚拟环境、pyproject.toml、wheel 与 sdist 的区别）
熟悉 pip 的日常使用
知道 requirements.txt 与 lockfile 的差别
可选：了解 SAT 求解或版本求解的基本概念

项目背景与完整档案

官方定位（README）："An extremely fast Python package and project manager, written in Rust." 一行替代 pip / pip-tools / pipx / poetry / pyenv / twine / virtualenv。官方给的数字是比 pip 快 10–100 倍。

基础信息：

PyPI 包名：uv，当前版本 0.13.4
协议：MIT OR Apache-2.0（双许可）
最新 release：0.13.4，发布于 2026-10-20
运行环境：macOS / Linux / Windows；核心操作不需要 Python 运行时
架构：一个 Rust workspace，50+ crate
核心技术：依赖求解基于 astral-pubgrub（SAT 求解）
异步运行时：tokio
CLI 框架：clap（derive 宏）

项目数据（截至 2026-10-21）：

⭐ Stars 90,969 ｜ 🍴 Forks 3,678
🔧 提交 11,155 ｜ 🐛 Open Issues 2,984
👥 贡献者 200+，Top 10 贡献 8,700+ 次
🗓️ 创建于 2023-10-02，最近推送 2026-10-21
💻 代码构成：Rust 21.1MB / Python 0.36MB

它解决什么问题

Python 工具链的普遍痛点：

工具碎片化：一个项目要用包管理、锁依赖、隔离环境、装 CLI 工具、管理 Python 版本、构建发布，六个工具六套配置六套缓存
pip 的性能问题：pip 的依赖求解是经典回溯算法，递归挑包挑版本，失败就回退换版本重试。依赖图一复杂，最坏情况会指数级爆炸
跨平台锁定难：同一个包在不同 Python 版本上要求不同版本是常态（numpy>=2,<3 ; python_version >= "3.11" vs numpy>=1.16,<2 ; python_version < "3.11"）。传统工具只能锁一个环境
磁盘重复：同一个 wheel 装进 10 个虚拟环境，就是 10 份实体字节

uv 的解法路径是递进的：

第一步，把工具收进一个二进制——所有子命令共享同一份缓存、同一套配置、同一份 lockfile。第二步，换掉求解器内核——用 PubGrub 的增量式单元传播替代回溯。第三步，把 lockfile 做成通用的——用 forking resolver 把解空间拆成多份独立的 resolution，一次锁定所有平台。

使用场景：

CI 提速：一个装 200 个依赖的 Python 项目，uv sync 通常在秒级完成，pip 可能要几十秒
多平台 monorepo：一份 uv.lock 覆盖 macOS / Linux / Windows × Python 3.9–3.13
工具统一：团队里 pip / poetry / pipx / pyenv 混用，uv 一次全替掉

快速上手

前提条件：macOS / Linux / Windows，无需预装 Python。

独立安装（推荐）：

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

Windows 用 PowerShell：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

也可以走 PyPI：

pip install uv
pipx install uv

装完先试一下：

uv --version
uv init my-project
cd my-project
uv add requests
uv run python main.py

常用命令：

# 装包（自动建虚拟环境）
uv add requests
 
# 装开发依赖
uv add --dev pytest ruff
 
# 同步锁文件里的依赖
uv sync
 
# 跑一个隔离的临时脚本
uv run python script.py
 
# 装一个命令行工具（相当于 pipx）
uv tool install ruff
 
# 升级某个包
uv lock --upgrade-package requests
 
# 审计依赖漏洞
uv audit

核心特性拆解

统一工具链——uv add / uv sync / uv run / uv tool / uv python / uv build / uv publish / uv pip 全在一个二进制里。uv pip 保留了 pip 的兼容接口，老脚本能平滑迁移。

项目管理模式——uv init 生成 pyproject.toml + uv.lock，uv add 同时改声明和锁文件。类似 poetry，但不需要学一套 DSL。

Python 版本管理——uv python install 3.13 下载并管理解释器，跨平台取同一个版本，Windows 上尤其有用。

通用 lockfile——一份 uv.lock 同时覆盖多个操作系统、多个 Python 版本、多个包来源。

原生构建后端——uv build 用内置的 uv-build-backend（PEP 517）构建 wheel 和 sdist，不需要额外的 build 工具。

依赖审计——uv audit 调 OSV 的 /v1/querybatch 接口批量查询漏洞（单次最多 1,000 个依赖），输出支持 json 和 sarif 格式。目前仍是 preview。

内容寻址缓存——相同内容的 wheel 收敛到同一条缓存记录。这是个 preview 特性，0.12.x 引入。

深度设计剖析

设计亮点一：放弃回溯，改用 PubGrub SAT 求解器

常规方案：

pip 用的是 resolvelib 的经典回溯：递归挑一个包、挑一个版本，装不上就回退换版本重试。这个算法实现简单，但最坏情况是指数级的——依赖图复杂时它会退化成「试遍所有版本组合」。而且它只解决「当前这一个环境」，换平台换 Python 版本就要重解一遍。

uv 的做法：

README 里直接写了："uv's dependency resolver uses PubGrub under the hood." 但真正有意思的是** uv 怎么用它**。

crates/uv-resolver/src/dependency_provider.rs 里有这么一段：

/// We don't use a dependency provider, we interact with state directly, but we still need this one
/// for type
pub(crate) struct UvDependencyProvider;
impl DependencyProvider for UvDependencyProvider {
    fn prioritize(...) -> Self::Priority { unimplemented!() }
    fn choose_version(...) -> Result<Option<Self::V>, Self::Err> { unimplemented!() }
    fn get_dependencies(...) -> Result<Dependencies<...>, Self::Err> { unimplemented!() }
}

整个 trait 的方法全是 unimplemented!()。 PubGrub 本该通过 DependencyProvider 抽象来与具体包源解耦，uv 直接扔掉这层抽象，改为直接操纵求解器的 State。

原因在 crates/uv-resolver/src/resolver/mod.rs 里：求解器跑在独立线程上，与异步元数据抓取流水线并行；每次单元传播之后，uv 立刻预访问所有候选包以便并行预取元数据：

state.pubgrub.unit_propagation(state.next)
// 传播后立刻预访问所有候选包
state.pubgrub.partial_solution.pre_visit(...)

PubGrub 的抽象粒度不够——它假设「选包」和「选版本」是原子的两步，但 uv 需要在这两步之间插入元数据并行预取、fork 调度、冲突重排。所以它绕过 trait 自己驱动。

为什么这么做：

PubGrub 的核心是增量式单元传播：冲突被记成 incompatibility（形如 {a 2, b 2}），可以增量撤销，而不是从头回溯。对 Python 生态那种「同一个包在不同 Python 版本上要不同版本」的图，这比回溯高效得多。

而 forking resolver（借鉴 Poetry）解决了另一个问题：把解空间拆成多个独立的 resolution，一次锁定所有平台。为了让 fork 位置稳定，uv 把每个 fork 的 resolution-markers 写回 lockfile——否则依赖顺序一变，fork 切点就漂移，下次解析结果和上次对不上。

工程价值与代价：

价值是跨平台一次锁定，以及解析失败时能给出「哪些包互相冲突」的可读错误链，而不是一句「无解」。

代价是 fork 是克隆式多分支，fork 数量可能爆炸（官方文档举例：flask 会分 3 个 fork），内存和求解时间随 fork 数增长。0.13.2 的 CHANGELOG 里连续几条性能条目都在削这块（"Reduce resolver memory use for large dependency graphs, forks, extras, and dependency groups"）。

还有一个细节有意思——uv 在 PubGrub 之外额外加了一条非 SAT 启发式：

we also use a heuristic that backtracks and switches the order of two packages if they have been conflicting too much

同一对包冲突超过 5 次后，把它们改成高冲突优先级并手动回退。这是 SAT 求解器上打的一个工程补丁。

设计亮点二：内容寻址缓存 + 三层链接语义

常规方案：

pip 的 HTTP 缓存目录里每个 wheel 存一份拷贝。装同一个包到 10 个虚拟环境，就是 10 份实体字节躺在磁盘上。pip 后来支持 --no-cache-dir，但那等于放弃缓存。

uv 的做法：

缓存桶按职责和版本号分开（crates/uv-cache/src/lib.rs）：

Self::SourceDistributions => "sdists-v10",
Self::FlatIndex => "flat-index-v7",
Self::Simple => "simple-v27",
Self::Wheels => "wheels-v7",
Self::Archive => "archive-v0",
Self::Files => "files-v0",

带版本号是刻意的——格式有破坏性变更就升版本号，多个 uv 版本可以安全共享同一个缓存目录。

关键在 Archive 和 Files 这两个桶的分工，源码注释写得很清楚：

/// A cache of unzipped wheels, stored as directories. This is used internally within the cache.
/// When other buckets need to store directories, they should persist them to
/// [`CacheBucket::Archive`], and then symlink them into the appropriate bucket.
Archive,
/// Content-addressed files that are hardlinked into cached archives.
Files,

于是有三层不同的链接语义：Archive 桶 ↔ 其他桶用 symlink；Files 桶的对象 ↔ Archive 用 hardlink；Archive ↔ 虚拟环境 site-packages 用 LinkMode。

而 LinkMode 的默认值是 Clone（写时复制），不是 hardlink：

pub enum LinkMode { Clone, Copy, Hardlink, Symlink }
impl Default for LinkMode {
    fn default() -> Self {
        if cfg!(any(target_os = "macos", target_os = "ios", target_os = "linux")) {
            Self::Clone
        } else {
            Self::Hardlink
        }
    }
}

macOS 的 APFS 和 Linux 的 btrfs/xfs 支持 reflink，克隆几乎零成本；不支持的文件系统降级到 hardlink；跨文件系统只能 copy。

内容寻址用 BLAKE3（crates/uv-extract/src/dirhash.rs），目录 hash 是「排序拼接（文件名 + 0xff 终止符 + 32 字节递归 dirhash）」。这里有个刻意的取舍，源码自己承认：

We don't hash any metadata about a file besides its name. In particular, that means that (unlike Git) we don't hash the Unix executable bit. [...] this gives us the property that the dirhash of an archive is the same as the dirhash of its unpacked files, even if the archive was prepared on Unix and unpacked on Windows.

落盘时按文件级 digest 的前 2 字节分片（files-v0/<shard>/<digest>），用 rayon 并行处理，shard 按文件数降序以重叠 IO。

为什么这么做：

内容寻址让「相同内容的 wheel」天然收敛到同一条缓存记录——不管它来自哪个 index、哪个平台变体、还是本地 rebuild 的产物。分片避免单目录百万级条目，兼顾 inode 和目录查找性能。

工程价值与代价：

代价有三。一是仍是 preview——content-addressed-cache 在 0.13.x 里依然标记为 preview，没有转正记录。二是有 CPU 开销——每次落盘都要 BLAKE3 哈希，解压时同步计算，CHANGELOG 里专门有优化条目（"Reduce allocations while extracting content-addressed wheels by reusing the hashing buffer across files"）。三是不哈希可执行位是刻意取舍，源码自己承认 "its possible that could cause bugs in some cases"。

项目细节补充

一个二进制怎么塞下这么多东西？

crates/uv/src/lib.rs 是个巨大的 match *cli.command，分支覆盖 Auth / Project / Tool / Python / Pip / Venv / Build / Publish / Workspace / Cache / Self / Clean。CLI 定义全在 crates/uv-cli/src/lib.rs 的 pub enum Commands 里，ProjectCommand 用 #[command(flatten)] 展开。

连构建后端都塞进了同一个二进制。crates/uv/src/commands/build_backend.rs 直接调 uv_build_backend::build_source_dist / build_wheel / build_editable / metadata，对应一个隐藏子命令：

frontend (PEP 517) which calls the Python shims which calls back into uv with this method

docs/concepts/build-backend.md 解释了原理：the uv executable also includes a copy of the build backend, which will be used during builds performed by uv。

uv audit 还在 preview，CLI 里打的是 #[preview(alias = "audit")] AuditCommand，未开启时会打 warning。底层服务在 crates/uv-audit/src/service/osv.rs，走 OSV 的 /v1/querybatch 批量查（单次最多 1,000 个依赖），再并发拉取完整漏洞记录。

一个容易踩的坑：uv 自己管 Python 版本，pyenv 也管，功能重叠，建议二选一。

项目资源汇总

官方资源

GitHub：astral-sh/uv
官方文档：docs.astral.sh/uv
开源协议：MIT OR Apache-2.0
更新日志：仓库内 CHANGELOG.md
贡献指南：仓库内 CONTRIBUTING.md
PyPI 包：uv（当前 0.13.4）
安装脚本：astral.sh/uv/install.sh

相关资源

PubGrub：uv 依赖求解的底层算法，Dart 出身，被移植到 Rust
astral-pubgrub：Astral 维护的 fork
Ruff：同一家公司的 Rust 工具，Python linter + formatter

媒体报道与延伸阅读

DeepWiki 架构导读（第三方自动生成，覆盖 crate 分层、PubGrub 求解器、缓存系统、构建后端等子系统）
解析器内部机制文档（官方文档，解释 universal resolution 与 fork 策略）

核心要点回顾

uv 把 pip / pip-tools / pipx / poetry / pyenv / twine / virtualenv 收进一个 Rust 二进制
依赖求解用 PubGrub SAT 求解器，且刻意绕过 DependencyProvider 抽象直接操纵求解器状态
forking resolver + 写回 lockfile 的 resolution-markers，实现一份 lockfile 跨平台通用
内容寻址缓存 + 三层链接语义（默认 Clone 而非 hardlink），同内容 wheel 只存一份

适合谁

被 pip 装依赖的速度折磨过的 Python 开发者
需要一个 lockfile 覆盖多平台多 Python 版本的项目
关注依赖求解算法、缓存设计这类底层工程问题的架构爱好者

一句话评价

它没有让 Python 生态变简单，它只是把「简单」这件事从你的命令行挪进了一个二进制文件。