uv:用统一工具链重塑Python包管理与依赖解析体验
如果你写过 Python 项目,大概率经历过这样的循环:先创建虚拟环境,再 pip install,然后在 requirements.txt 里手动记录依赖,遇到版本冲突就 pip 一个个试。这套流程在单机小项目上勉强够用,但一旦进入多环境协作、CI 部署、多 Python 版本切换,痛点就会被无限放大。我最早注意到 uv 是因为它号称“比 pip 快 10-100 倍”,后来真正替换掉 pip/poetry 组合后才发现,速度只是最表层的好处,它更是一个把依赖解析、环境管理和项目工程化重新整合的工具。所以这篇文章我不想只写“用法清单”,而是尽量把 uv 背后的设计逻辑、我在实际项目中踩过的坑,以及如何用它把项目工程化做扎实,一次性讲清楚。
1. 为什么是 uv:Python 包管理的痛点与被重构的体验
1.1 从 pip/venv 到 uv:我经历了什么
在 uv 出现之前,Python 包管理一直处于一种“半分裂”状态。标准库给了我们 venv 创建虚拟环境,pip 负责安装包,requirements.txt 负责记录顶层依赖,但项目一旦变大,这三者的组合就开始失灵。pip install 默认安装的是“当前满足要求的最新版本”,它不会帮你考虑这个包将来会不会升级,也不会主动锁定传递依赖的具体版本。于是过了一个月,同事拉下代码,pip install -r requirements.txt 之后跑出来的行为可能和你不一致,因为某个子依赖悄悄升了一个小版本,修了 bug 却也引入了兼容性变化。
我自己最早用的是 pip + requirements.txt 手工维护,后来换过 pip-tools,也试过 poetry。pip-tools 解决了“锁定”问题,但仍然需要同时维护 requirements.in 和 requirements.txt 两个文件,且每次手动执行 pip-compile 再 pip-sync,流程不够顺畅。poetry 把虚拟环境和依赖声明统一到 pyproject.toml,理念很先进,但它的依赖解析速度实在让人着急,尤其当项目有几十上百个依赖时,一次 poetry lock 能让你去泡杯茶再回来。而且 poetry 默认把虚拟环境建在全局缓存目录下,项目里看不到 .venv,有些同事会因此产生“我到底装到哪了”的困惑。
uv 的出现实际上是在解决这些结构性痛点,而不是单纯把 pip 加速。它把 Python 解释器安装、虚拟环境创建、依赖解析、锁定、同步、运行命令这几个步骤整合成了一个工具链。你会发现你不再需要手动记“先 python -m venv,再 pip install,再 pip freeze > requirements.txt”这套机械流程。这就是我要切换到 uv 最原始的动力:它把“项目依赖”当成一个整体来管理,而不是把每个环节拆开交给不同工具。
1.2 uv 的核心优势:速度、统一与确定性
先谈速度。uv 用 Rust 编写,内部采用全局缓存和并行下载策略,安装依赖时不会一个一个地把 wheel 拉下来,而是并发获取并做硬链接处理。实际体验中,冷缓存下安装一个包含几十个包的项目,往往只需要几秒钟;热缓存下甚至不到一秒。这种速度差异不是“快一点”,而是从根本上改变了操作习惯。以前我更新一个生产项目依赖,会特意挑一个空闲时间执行,因为 pip install 可能要跑几分钟,现在 uv sync 几乎可以随时执行。
统一是指 uv 替代了多个工具:它的 uv venv 替代 python -m venv,uv pip 可以兼容 pip 的用法,uv add 和 uv lock 替代 pip-tools 或 poetry 的依赖声明与锁定,uv python install 可以安装指定版本的 Python 解释器,替代 pyenv 常用场景。这意味着一个团队可以用同一套 uv 指令完成从 Python 安装到依赖部署的全部环节,不再需要每个人各自安装一套 pyenv、poetry、pip-tools 组合。
确定性则体现在 uv.lock 文件上。只要把 pyproject.toml 和 uv.lock 提交到仓库,任何机器上执行 uv sync 都会得到完全一致的虚拟环境和依赖树。这一点在团队协作和 CI 中尤其重要。以前用 requirements.txt 时,哪怕你固定了顶层版本,子依赖仍然可能漂移;而 uv.lock 记录了所有包的精确版本、来源哈希和依赖关系,像是给整个依赖树拍了一张快照。我自己的习惯是:任何更新依赖的操作都必须重新生成 lock 文件,并且把 lock 文件视为代码的一部分来 review。
2. uv 的安装与基础使用:从零到第一个虚拟环境
2.1 安装 uv:三种系统下的姿势
uv 的官方推荐安装方式是使用安装脚本。我见过很多新手会在这一步卡住,其实核心只有一点:uv 是一个独立运行的二进制工具,不一定要先装 Python 才能装 uv。这点和 pip 不一样,pip 必须先有一个 Python 环境,而 uv 却可以自己负责下载 Python。
Windows 下,在 PowerShell 中执行:
这行命令会下载 uv 到用户目录下的 .local\bin 或 %USERPROFILE%\.local\bin,并加入 PATH。如果你之前看到过 c:\users\administrator\appdata\local\uv 这种路径,那通常是 uv 的缓存目录,而不是可执行文件所在目录。可执行文件一般在 c:\users\<用户名>\.local\bin\uv.exe。如果后续在终端里 uv 命令找不到,先检查这个路径是否在系统 PATH 中。
macOS 和 Linux 下用:
脚本会把 uv 安装到 ~/.local/bin,同时自动配置 PATH。如果你的系统连 curl 都没有,也可以先用包管理器装一个,或者从 GitHub Releases 页面手动下载对应架构的二进制压缩包解压后放到 ~/bin。
还有一个比较贴近 Python 生态的安装方式:pip install uv。如果你机器上已经存在 Python 环境,这种方式最快,几秒钟就能装好。不过它要求你有一个可用的 pip,属于“先有鸡还是先有蛋”的场景。我个人更推荐官方脚本,因为这样 uv 独立于当前 Python,不容易被某次 pip uninstall 误伤。安装完成后,执行 uv --version 验证。如果能看到版本号,说明安装成功。
2.2 核心命令速查:init、add、run、sync
当你的机器上已经拥有 uv 之后,从一个空目录开始构建 Python 项目,我习惯用下面这套流程。首先创建一个目录并初始化:
uv init 会生成一个最小的 pyproject.toml,同时可能创建 src/my_demo 目录和初始代码结构,具体取决于你使用的是新模板还是旧模板。紧接着,直接添加依赖:
这一步可能会让你惊讶:uv add 会自动创建一个名为 .venv 的虚拟环境(如果不存在),然后解析依赖并安装。你不必先手工 uv venv,也不必先激活环境。解析完成后,它会生成 uv.lock 文件,并把顶层依赖写入 pyproject.toml 的 dependencies 列表中。
之后要运行项目中的代码:
uv run 会自动确保虚拟环境已同步(如果缺少依赖会自动安装或提醒),然后在当前项目的虚拟环境中执行命令。这意味着你再也不需要在每台机器上手动执行 source .venv/bin/activate。如果是临时跑一个工具,uvx 甚至可以直接运行而不污染当前项目,比如 uvx ruff check .。
当项目被 clone 到新机器上时,只需要两个命令:
uv sync 会根据 uv.lock 创建虚拟环境并安装所有依赖,安装完的虚拟环境和你的开发环境几乎完全一致。至于 uv remove,用来移除依赖后会同步更新 pyproject.toml 和 uv.lock,不用像 pip 那样自己再去 freeze 一次。
2.3 虚拟环境切换与 Python 版本管理
uv 管理虚拟环境的方式我认为比传统方案更直观:每个项目的虚拟环境默认就直接放在项目根目录的 .venv 下面。如果你用过 poetry 会发现 poetry 默认把环境放在缓存目录,项目目录里看不见,这导致很多人困惑到底激活的是哪一个。uv 的 .venv 就在眼前,并且支持多 Python 版本切换。
先看如何安装其他版本的 Python。比如项目需要 Python 3.11 和 3.12 分别测试:
之后在项目里固定 Python 版本:
这会生成一个 .python-version 文件。一旦有了这个文件,后续 uv sync 会自动优先选择 3.11 版本来创建虚拟环境,不需要你在每台机器上去手动指定解释器路径。如果你某个项目临时想换到 3.12 测试,直接修改 .python-version 或重新执行 uv python pin 3.12,然后 uv sync 会自动重建虚拟环境。这种“声明式 Python 版本管理”比手工创建 venv 后在文件里记一段说明可靠得多。
切换虚拟环境本身也不复杂。大部分时候我会让 uv run 自动处理,不需要显式激活。但如果你想在终端里进入环境做调试,依然可以激活:Linux/macOS 下执行 source .venv/bin/activate,Windows 下执行 .venv\Scripts\Activate.ps1。这和你以前的 venv 体验完全一致。值得留意的是,uv 会优先使用项目内的 .venv,而不是去 PATH 中找 python。如果你在项目里跑 python 而不是 uv run python,可能会调用系统 Python,导致依赖不一致。所以我后来养成了习惯:在 uv 项目里统一使用 uv run,连测试、lint 命令都包裹在 uv run 里执行。
3. 依赖解析的底层逻辑:如何做到“一次解析,处处可复现”
3.1 uv lock 与锁定文件的工作原理
很多初学者会把 requirements.txt 和 uv.lock 混为一谈,但它们解决的问题并不完全相同。requirements.txt 本质上是“筛选条件的集合”,里面写着 numpy==1.26.4、requests==2.31.0 这样的条目,但它不记录这些包之间的互相依赖关系,也不记录在不同平台上的差异。而 uv.lock 是一张完整的依赖图。
我们假设 pyproject.toml 里声明了:
当执行 uv lock 时,uv 会读取 requests>=2.31 这个约束,然后查找到所有满足条件的 requests 版本,再解析 requests 自身依赖的 urllib3、certifi、charset-normalizer 等包的版本范围,一层一层往下,最终得出一个满足所有约束的、精确到每个包具体版本和哈希值的解决方案。这个结果写入 uv.lock。
为什么需要锁定文件?因为语义化版本(SemVer)在 Python 生态里并不是绝对可靠,一个包升个小版本也可能引入行为变化。如果不做锁定,今天 uv add requests 装的可能是 2.31.0,下个月同一个命令装的可能是 2.32.3,导致同样的 pyproject.toml 在不同的时间点产生不同的环境。uv.lock 的意义是:只认第一次解析出来的那组版本编号,后续 uv sync 永远按照 lock 文件安装,除非你明确执行 uv lock 或 uv add 升级。
uv sync 的过程是这样:先检查 uv.lock 是否存在,如果存在就直接按锁定的版本安装,不再重新解析;如果不存在或与 pyproject.toml 不一致,则提醒你先执行 uv lock。这保证了 CI 环境里不会有任何“碰运气”的成分。
3.2 解析策略与冲突解决
uv 的依赖解析器采用的是回溯(backtracking)算法。你可以把它想象成走迷宫:当前路径碰到死胡同,就退回到上一个分岔口换一个方向继续走。比如包 A 依赖 B<2,包 C 依赖 B>=2.0,并且 A 和 C 都是项目依赖,那么解析器会先尝试选择 B 的某个版本,然后发现无法同时满足两个约束,就会回溯换一个版本组合,直到找到一个可行的方案,或者确定无解。
这个过程中,uv 会缓存已经解析过的包的元数据,所以第二次解析会快很多。我之前用 poetry 解析一个中等规模项目可能需要几十秒,而 uv 通常几秒钟就能完成。这里有个容易被忽略的关键点:uv 在解析时并不需要下载完整的 wheel 包,它只下载包的元数据(metadata),所以即使依赖很多,网络开销也很小。只有最终确定了版本组合后,才会去下载实际安装所需的 wheel。
如果项目确实存在无法自动解决的冲突,uv 提供了 dependency-overrides 机制。在 pyproject.toml 中,你可以强制将某个传递依赖覆盖为指定版本。但这里一定要提醒:覆盖依赖是很危险的操作,它相当于手动替解析器做决定,可能会引入运行时不兼容。我一般只在紧急修复时使用,并且会在 commit 信息里标明原因。还有一种更安全的方式是使用 constraint 文件,用于限定上限而不是精确版本,但 uv 项目的 pyproject 里更常用的是 dependency-overrides。总之,优先让解析器自己做决定,覆盖只是最后手段。
3.3 与 pip-tools / poetry 的对比
为了更直观地理解 uv 的定位,我用一个表格对比它和传统方案的区别:
| 能力 | pip + requirements.txt | pip-tools | poetry | uv |
|---|---|---|---|---|
| 创建虚拟环境 | 手工 venv | 手工 venv | 自动 | 自动 |
| 依赖声明 | requirements.txt | requirements.in | pyproject.toml | pyproject.toml |
| 精确锁定 | 不完整 | 有 | 有 | 有(uv.lock) |
| 传递依赖管理 | 手动 | 自动 | 自动 | 自动 |
| Python 版本管理 | 无 | 无 | 部分 | 内置 |
| 解析速度 | 快但粗糙 | 慢 | 慢 | 快 |
| 运行命令 | 需要激活 | 需要激活 | poetry run | uv run |
表格里的重点在于:uv 并不是“pip 的替代品”,而是把散落在各个工具里的能力重新整合,并且补上了 Python 版本管理这块拼图。如果你当前的 pip-tools 玩法已经足够,并不需要立刻抛弃,但如果你想减少工具链数量、提升解析效率,并且希望新同事接手项目时只靠一个工具就能完成所有环境操作,uv 确实是最值得迁移的方向。
4. 项目工程化实战:用 uv 搭建一个可维护的 Python 项目
4.1 标准项目结构设计
工程化不是把依赖装好就完了,更重要的是项目结构能让团队快速理解、持续演进。我推荐用下面这样的目录结构:
之所以采用 src 布局而不是直接在根目录放包,是因为这能避免“包名和项目名混淆导致导入错误”的经典问题。当你的代码放在 src/my_project 内部时,测试代码通过安装后的包名导入,而不是靠相对路径,这样更贴近真实使用方式。uv 生成的模板也默认采用了 src 布局,这符合现代 Python 工程习惯。
pyproject.toml 中需要声明项目元数据,uv 会读取它来管理依赖。一个最小可用的版本:
.python-version 文件内容就是类似 3.12 的一行,它配合 uv 管理 Python 解释器版本。.gitignore 至少要忽略 .venv、__pycache__、*.pyc 这些内容。有了这套基础结构,任何同事 clone 后执行 uv sync 就能得到可运行的环境,不需要阅读 README 先生存指南。
4.2 依赖分组与开发依赖管理
在工程化实践中,依赖通常需要分成生产依赖和开发依赖。生产依赖是运行时需要的包,比如 FastAPI、SQLAlchemy;开发依赖是测试和代码规范用的包,比如 pytest、ruff、mypy。如果混在一起,会导致生产镜像里安装一堆无用工具,增加体积和攻击面。
uv 通过 dependency-groups 来管理开发依赖。在 pyproject.toml 中,你可以添加:
执行 uv add --dev pytest 时,uv 会自动把 pytest 添加到 dev 组里。在执行 uv sync 时,默认会安装 project.dependencies 和 dependency-groups.dev 中的所有依赖。如果只在生产环境部署,可以执行:
这样就不会安装 pytest 等开发工具。如果你还有其他分组,比如文档构建:
然后同步时加上 --group docs 即可。这种分组能力让我在写 Docker 多阶段构建时受益很多:构建阶段用完整 dev 依赖跑测试和 lint,最终运行阶段只保留生产依赖。
4.3 与 VSCode/PyCharm 集成配置
命令行再方便,日常写代码还是需要 IDE 配合。uv 创建的项目环境位于 .venv,IDE 只要选中这个解释器即可。
在 VSCode 中,打开项目后使用命令面板(Ctrl+Shift+P),执行 “Python: Select Interpreter”,选择 .venv 下的 Python。Windows 下通常是 .venv\Scripts\python.exe,Linux/macOS 下是 .venv/bin/python。如果你的 VSCode 已经安装了 Pylance/Python 扩展,它可能会自动识别 .venv,但如果没有,手动添加路径也不复杂。
还有一个容易被忽略的点:.python-version 文件不会影响 VSCode 的默认解释器,但会影响 uv 创建环境时使用的 Python 版本。所以最佳实践是:先在项目根目录用 uv python pin 3.12 固定版本,再执行 uv sync,最后让 VSCode 选择 .venv 里的解释器。这样 IDE 看到的 Python 版本和你用 uv run 跑命令时完全一致,避免出现“VSCode 里 import 成功,命令行里却 ModuleNotFoundError”的诡异问题。
PyCharm 用户可以在 Settings > Project > Python Interpreter 中选择 “Existing environment”,然后指向 .venv 下的解释器。如果你希望 PyCharm 的终端自动激活虚拟环境,可以把终端设置为 source .venv/bin/activate(Windows 上执行 .venv\Scripts\activate),或者在运行配置里直接用 uv run python script.py 来替代直接运行 Python。
此外,如果你在 VSCode 中运行 Jupyter Notebook,建议也把内核指定到 .venv 环境,否则会默认使用全局 Python,造成依赖不一致。我自己习惯通过 uv run jupyter lab 启动服务,这样 notebook 会运行在项目环境中,省去很多 import 报错。
5. 常见问题与排查技巧实录
5.1 安装 uv 时提示执行策略/权限不足
Windows 用户在 PowerShell 里执行官方安装脚本时,很可能会遇到“无法加载文件,因为在此系统上禁止运行脚本”的报错。这是因为 PowerShell 默认执行策略限制了脚本运行。解决方案有两种:一种是用 -ExecutionPolicy ByPass 参数临时绕过,另一种是更保守的方式,手动下载 uv-x86_64-pc-windows-msvc.zip 并解压到某个目录,然后把该目录加入 PATH。
如果是 Linux/macOS 用户执行安装脚本时报 Permission denied,通常是因为当前用户没有对安装目录(比如 /usr/local/bin)的写权限。遇到这种情况,不要急着 sudo 强行安装,优先改用用户目录安装:pip install --user uv,或者把安装脚本下载下来的 uv 二进制移动到 ~/.local/bin 下。我个人更倾向于让 uv 待在自己的用户目录,这样升级和卸载都不需要 root 权限,也不会污染系统级 Python。
还有一个高频问题:安装成功了,但新开的终端仍然提示 uv: command not found。这通常是 PATH 没有刷新。可以尝试重新打开终端,或者执行 source ~/.bashrc / source ~/.zshrc。如果依然不行,检查安装脚本输出的实际路径,手动把 export PATH="$HOME/.local/bin:$PATH" 添加到 shell 配置文件中。
5.2 缓存路径与磁盘占用
uv 之所以快,很大程度上依赖它的全局缓存。你可能注意到热词里有 c:\users\administrator\appdata\local\uv,这其实就是 Windows 下 uv 缓存和下载数据所在的位置。在 Linux 下缓存目录通常位于 ~/.cache/uv,macOS 是 ~/Library/Caches/uv。
缓存会随着时间推移逐渐膨胀,尤其是你频繁切换 Python 版本和依赖版本时。如果你发现磁盘空间紧张,可以用 uv cache clean 清空全部缓存,或者 uv cache prune 只清理无用的缓存条目。prune 比 clean 温和,它会保留当前项目和最近可能用到的包缓存,我推荐日常使用 prune。
如果你希望把缓存放到另一个磁盘或目录,可以设置环境变量 UV_CACHE_DIR。例如在 CI 环境中,你可以把缓存目录指向项目的临时目录,但通常更高效的做法是在 CI 里持久化缓存,这样每次构建不用重新下载所有依赖。uv 也提供了 uv cache dir 命令来查看当前缓存路径。理解缓存机制后,你就不会因为找不到 .venv 或“C 盘突然少了几个 G”而惊慌。
5.3 与系统 Python/Debian 包管理的冲突
很多 Debian/Ubuntu 用户的系统 Python 是由 APT 管理的,/usr/bin/python3 和 python3-pip 都属于系统软件包。如果贸然用 pip install --system 或 sudo pip install 往系统 Python 里装包,很容易破坏系统工具的依赖。现代 Linux 发行版普遍开启了 PEP 668 保护,直接在系统环境里 pip install 会报 error: externally-managed-environment,这是好事,它阻止你做傻事。
uv 的设计天然规避了这个问题。它不会去动系统 Python,而是自己管理一套独立的 Python 解释器(默认下载到用户缓存目录)。当你运行 uv sync 时,它创建的是项目内的 .venv,所有依赖都安装在里面,不碰系统目录。所以即使你的 Ubuntu 刚装好,还没有 /usr/bin/python3,只要安装了 uv,它也能自动下载对应版本的 Python 并完成环境搭建。这也是我建议新机器优先安装 uv 而不是先折腾 Python 版本的原因。
如果你确实需要和系统已经安装的 Python 共存,可以告诉 uv 使用系统 Python:uv venv --python /usr/bin/python3。但除非有特殊要求,我不建议这么做,因为 CI 机器和 Docker 镜像里的 Python 会和你本机版本不一致,失去可复现性;让 uv 统一管理反而更省心。
5.4 uv 在 CI/CD 中的实践建议
在 CI 中使用的核心字符串是 uv sync --frozen。这个参数表示“不要更新 lock 文件,完全按照已有的 uv.lock 安装”。因为 CI 环境不应该生成 lock 文件,它应该忠实地复现你提交时的状态。如果 pyproject.toml 和 uv.lock 不一致,--frozen 会让命令失败,这可以及时暴露问题。
GitHub Actions 中,我通常使用官方 setup 步骤:
这样先把 uv 安装好,再同步依赖。为了加速 CI,可以配置缓存:在 setup-uv 之前设置 UV_CACHE_DIR 为 GitHub Actions 的缓存目录。Docker 构建时也可以采用多阶段:先用 uv sync --frozen 安装完整依赖并跑测试,最后在 runtime 镜像里只复制 .venv 和应用代码,使用 uv sync --no-dev 或者直接通过 uv run --isolated 运行。
在 CI 中另一个常见坑是:如果没有显式激活虚拟环境,python 命令可能指向系统的 Python。所以所有涉及 Python 的命令都应该通过 uv run 来执行,或者先 source .venv/bin/activate。这虽然看起来多打几个字,但能避免大量“本地能跑 CI 不行”的疑难问题。
最后说一下我对 uv 的真实感受。用了大约半年之后,最明显的改变并不是安装依赖的速度,而是心理上的确定性:无论是新电脑、新服务器还是新同事的笔记本,只要拉下代码执行 uv sync,环境就一定和之前保持一致。这种“这也能跑”的底气是 pip 时代很难获得的。如果你当前正在被 requirements 漂移、Python 版本混乱、依赖解析卡顿这些问题困扰,我认为花一两天把项目迁移到 uv 是值得的。可以先从一个不太重要的库项目开始练习,熟悉 uv add 和 uv run 的节奏,再逐步覆盖主项目。迁移时尽量保持 pyproject.toml 中的版本范围宽松,让 uv 自己选择最合适的组合,不要迷信手工锁定版本。随着你对 uv 的信任度提升,你会慢慢发现包管理这件事,原本不必那么痛苦。