刚把手上一个用了三四年的 Python 项目从pip venv requirements.txt pyenv pipx这套老阵容整体切到了uv上目前跑了一周多CI 也换完了整体体感确实值得单独写一篇记录。这个标题我早就想占了现在终于有内容可填。如果你也在纠结“Python 工具链要不要换”、“uv 到底香不香”、“换了之后之前那套还能不能兼容”这篇就是我这次迁移的完整复盘从为什么换、怎么换到迁移中踩过的坑和最终的日常用法一次都讲清楚。1. 为什么现代 Python 项目都在谈工具链重构先说一个很多人都有过的困惑Python 本身很简单但管理 Python 的那堆工具链一点也不简单。pip管包venv管环境pyenv管解释器版本pip-tools管锁依赖pipx管装命令行工具每个工具单看都挺好但要组合起来用就需要一套心照不宣的流程而流程一旦断一环项目就开始变得很难受。现代 Python 项目的“现代”很大程度上就是把这几件割裂的事重新整合。1.1 “在我电脑上能跑”的根因正是旧工具链的裂痕我之前维护的项目依赖藏在requirements.txt里看起来没问题但真正部署的时候问题都出在细节上requirements.txt里写的是requests2.31,3这种范围约束装到不同环境的机器上解析出的实际版本可能不一样于是就会出现“明明按照文档装好了依赖线上却复现不了 Bug”的情况。问题的根源不是包而是依赖解析这件事一直处于一种比较松散的状态。pip其实一直在改进但它的依赖解析仍然是按需解析也就是说它不会为整个项目建立一个统一的、锁死的依赖视图而是遇到什么装什么。如果两个包之间存在版本冲突pip只会告诉你“找不到一个满足要求的版本”然后让你自己去排查是哪个依赖的哪个版本卡住了。这种排查在依赖树简单时还能接受一旦涉及数十个传递依赖就非常费神。现代工具链的第一个核心诉求就是把这一步变成明确的、可复现的解析结果。1.2 虚拟环境、解释器版本、系统包管理器三者长期分家另一个让我下定决心换工具的问题是 Python 版本解释器的管理。pyenv可以装多个 Pythonvenv可以为项目建独立环境但这两者之间其实没有天然的联动。我记得有次在服务器上新拉了一个项目pyenv里装的是 3.11但项目要求 3.12我第一反应是先pyenv install 3.12再去手动建 venv再手动激活然后才能pip install一套下来少说五分钟。如果中间某个版本编译缺少依赖时间就更不可控。这套流程本身没什么错但它对“项目”这个概念的理解太弱了。理想状态下一个项目应该自带一张描述清单说明它需要哪个 Python 版本、哪些依赖、依赖锁定在哪个版本然后一个命令把环境完整拉起。现实中的旧工具链把这些拆成了四个工具的职责也就是每个人干好一小块但没有人负责整体编排。1.3 脚本运行和临时工具被长期当成“下等公民”还有一类隐性成本来自小脚本和一次性工具。我想跑一个临时数据处理脚本第一反应是新建一个 venv、装pandas、装requests跑完再删掉。如果只是临时装一个命令行工具还得去查pipx怎么用。这些需求不算高频但每次都要先做一遍环境准备就让人不太舒服。后来我意识到现代工具链的共识是想办法把“环境准备”这件事隐藏起来让工具自动推断“这个脚本需要什么依赖”或者“这个工具需要装到哪个隔离环境”而不是让开发者自己记流程。uv在这一点上做得比较彻底它把 Python 解释器管理、虚拟环境、依赖解析、依赖安装、脚本运行、工具安装全部收编成一个二进制。这也是为什么我说它是“现代化 Python 工具”里目前最值得投入学习的一个。2. uv 是什么把哪些“旧三件”收编了uv本质上是一个用 Rust 写成的、面向 Python 生态的一体化工具链。它不是一个简单的pip加速器而是把过去一套组合里的多个角色集成到了一个命令行里。第一次用的时候最直观的感受是原来一直以为 Python 工具链就该是那样旧工具的许多别扭之处其实是历史包袱换了之后才发现可以清爽很多。2.1 一个二进制七个角色一次到位从功能上看uv目前能覆盖几个主要的场景一是通过uv python install管理 Python 解释器版本二是通过uv venv或项目内自动创建的.venv管理虚拟环境三是通过uv add、uv remove、uv lock管理依赖声明与锁文件四是通过uv sync把锁文件同步到环境里五是通过uv run直接在项目环境下执行命令或脚本六是通过uv tool install安装全局命令行工具七是uv build构建分发包配合uv publish发布。也就是说以前我要装 Python 用pyenv建环境用venv装包用pip锁版本用pip-tools的pip-compile装工具用pipx。现在这些全部收进了一个二进制命令之间通过项目文件比如pyproject.toml、uv.lock、.python-version产生联动。最核心的变化是项目的状态不再分散在环境里而是由文件精确描述环境只是这份描述的产物。2.2 从 pip/venv 到 uv 的对比直观感受差别用表格看对比会更清楚这里基于我实际项目的使用体会整理场景旧方案uv 方案关键差别创建项目环境python -m venv .venv source .venv/bin/activateuv sync环境自动创建无需手动激活安装依赖pip install requests然后手动写入 requirementsuv add requests同时更新 pyproject 和锁文件复现环境pip install -r requirements.txtuv sync基于uv.lock完全锁定跨平台一致管理 Python 版本pyenv install 3.12 pyenv local 3.12uv python pin 3.12自动下载、无需源码编译锁依赖pip-compile requirements.in -o requirements.txtuv lock原生支持语义化版本与 peer 依赖运行脚本先激活环境再python script.pyuv run script.py自动检测依赖声明省去激活装命令行工具pipx installuv tool install更快的全局缓存自动隔离2.3 “比 pip 快很多”的背后不只是语言优势很多人第一次听说uv是因为它“速度极快”但真正用下来速度只是它众多优势里比较直观的一项。它快的原因有三层第一层是全局缓存。uv会把下载的 wheel 缓存在用户级的缓存目录里同一个包在多个项目里使用时不需要重复下载。这点pip其实也有缓存但uv的缓存命中率和组织形式更高效。第二层是并行安装与链接。uv在安装时会把依赖分发到多个并发任务中下载和安装可以同时进行而在能使用硬链接的环境下从缓存链接到虚拟环境几乎是一瞬间的事不需要复制文件。第三层才是 Rust 带来的解析性能。依赖解析是一个涉及大量比较和回溯的过程用编译型语言来写解析器相比纯 Python 实现有数量级的性能提升。我实测在同一个项目里旧方案冷环境安装依赖大约需要 90 秒uv sync大概是十几秒如果缓存已经存在甚至不到两秒。当然不同项目和网络环境差别很大但趋势是很明显的。3. 安装 uv 与最小可用配置如果你看到这里已经打算动手试一下那这一节就重点讲怎么装、装完之后怎么配置一个现代 Python 项目的基础结构。这部分内容尽量精简到可以直接抄作业。3.1 安装方式选型独立安装器优先uv提供好几种安装方式我的建议是优先使用官网提供的独立安装脚本或者常见系统包管理器里的uv包如果版本够新。安装脚本基本是把二进制放到用户目录下比如~/.local/bin或~/.cargo/bin然后加入 PATH。# 使用官网提供的安装脚本以 Unix 类系统为例 curl -LsSf https://astral.sh/uv/install.sh | sh如果你不想访问外网也可以直接下载 GitHub Release 里对应平台的二进制压缩包解压后放到 PATH 里。uv是单一静态二进制不需要额外运行时这点对离线环境比较友好。注意如果你之前在 Python 环境里跑过pip install uv我建议卸载掉改用独立二进制。用 pip 安装的 uv 本身依赖 Python 环境这会让“管理 Python 环境的工具依赖 Python”这件事变得很绕升级方式也更别扭。独立二进制才是 uv 推荐的使用方式。装完之后运行uv --version确认一下。目前 uv 的版本迭代很快新功能基本每个月都有更新建议隔一段时间升级一次uv self update这个命令会从官方渠道拉取新版本不需要走系统包管理器。3.2 初始化项目一条命令生成的现代结构现在初始化一个项目用uv init比如# 创建一个应用类型的项目默认结构 uv init demo-app cd demo-app # 或者创建一个库类型的项目会采用 src 布局 uv init --lib demo-lib跑完之后目录下至少会生成这么几个文件pyproject.toml项目元数据和依赖声明、.python-version指定的 Python 版本、.gitignore自动忽略.venv等目录、main.py或src/初始结构。注意它默认不会帮你创建虚拟环境环境会在第一次执行uv sync或uv run时自动生成。pyproject.toml是项目的灵魂一个最小可用的示例大概长这样[project] name demo-app version 0.1.0 description A demo project readme README.md requires-python 3.11 dependencies []3.3 pyproject.toml 的关键字段初始化后按需调整进入实际项目后pyproject.toml还会用到几个关键配置块[project]块负责声明项目元信息和直接依赖。requires-python非常关键它约束了环境可用的 Python 版本范围。uv在创建环境和解析依赖时都会参考这个字段所以不要随意写一个太宽的范围否则它可能在解析时为了照顾太老的 Python 而选出旧版本依赖反而给你带来兼容性问题。[tool.uv]块负责 uv 的配置比如默认索引源、额外解析选项等。如果你在一个网络隔离环境里工作很可能需要在这里配置私有源。例如想用某个 PyPI 镜像时可以在pyproject.toml里这样写[tool.uv] index-url https://mirror.example.com/pypi/simple如果项目里同时要区分开发依赖和生产依赖可以引入依赖组dependency group的概念这个后面讲操作时再展开。此外还有个.python-version文件它只写一行内容比如3.12。这个文件的优先级很高uv会自动找到它来确定项目使用的 Python 版本。如果你希望团队成员都用同一个版本这个文件比在文档里写“请安装 Python 3.12”靠谱多了。实操心得初始化完成后我建议先把.python-version固定好再开始加依赖。因为依赖解析结果和requires-python、.python-version 是绑在一起的。如果你先加了一堆依赖才发现 Python 版本写错了重新解析会多花时间。4. 日常高频操作依赖、锁文件、同步与升级工具链好不好用不在于宣传了多少概念而在于日常操作是否顺手。这一节是 uv 每天都会用到的高频操作。4.1 添加与移除依赖无需再想两件事以前用pip install x安装之后还要手动把新依赖写进requirements.txt经常写着写着就忘了。用uv add会把依赖写入pyproject.toml并同步更新uv.lock一步到位uv add requests uv add httpx0.27,1.0 uv add pytest --group dev第二条命令展示了如何指定版本范围uv 会优先保留你声明的约束并在解析时寻找满足约束的最新版本。第三条把 pytest 放进了 dev 组这样生产环境安装时就不会带上测试依赖。移除依赖同理uv remove requests uv remove pytest --group dev这里有个值得养成的习惯依赖的版本范围尽量不要太宽。1.0看起来省心但半年后可能解析出一个大版本更新的包带来不兼容变更。比较稳妥的做法是先给出一个合理的下限再把上限限制在主版本比如requests2.31,3。4.2 生成锁文件与同步环境可复现的关键一步uv.lock是整个工具链里我最喜欢的一个产物。它不只是一个简单的“版本号列表”而是对整棵依赖树的完整锁定包括每个依赖的来源、解析出的版本、哈希校验值、平台条件等。这意味着同一份代码和同一个uv.lock在任何平台、任何时候同步得到的依赖版本树都是一致的。手动触发更新的命令是uv lock如果只是要把锁文件里记录的依赖环境同步到本地则用uv sync首次运行uv sync时它会根据.python-version自动寻找或下载合适的 Python 版本创建.venv然后安装uv.lock里锁定的依赖。不需要手动激活环境也不需要单独执行pip install。在 CI 或 Docker 里我强烈建议加一个参数uv sync --frozen--frozen的意思是不更新锁文件只按照现有uv.lock执行同步。这对 CI 非常合适因为锁文件是在提交时确定的CI 环境不应该试图去更新它否则可能出现“本地能复现、CI 解析出的版本不同”的情况。4.3 锁文件更新策略整体升级还是精确升级依赖装在环境里之后不是一劳永逸的。你需要定期升级依赖以获得安全修复和新功能但升级粒度非常重要。uv区分了“整体升级”和“指定包升级”# 整体升级所有依赖到最新并重新锁定 uv lock --upgrade # 只升级某个包其他依赖保持锁定 uv lock --upgrade-package httpx我通常的做法是日常维护只对目标包执行--upgrade-package这样可以把变动范围控制到最小只有在新版本周期或长期维护时才做一次整体升级但整体升级前后会跑一遍完整的测试套件。用--upgrade-package时即使 httpx 的新版本要求某个传递依赖升级uv 也会主动更新受影响的依赖但不会动项目里其他直接依赖。注意升级依赖前最好先看一下uv.lock的变动内容。没错uv.lock 是文本文件可以直接 diff。养成先看 diff 再提交的习惯能避免很多“为什么升级后测试挂了”的问题。4.4 依赖组与可选特性处理开发/测试/生产环境现代项目里一个环境往往不够用。测试需要 pytest、mypy 等工具这些不应该出现在生产环境的依赖里。uv 用 dependency group 来管理这类场景常用的命令如下# 在 pyproject.toml 中声明一个 dev 组 uv add pytest --group dev # 同步默认依赖 dev 组 uv sync --group dev # 只同步默认依赖不装 dev 组 uv sync # 同步所有组依赖 uv sync --all-groups另一种需求是发布库时定义可选特性extra比如用户安装时可以选装某个功能模块[project.optional-dependencies] socks [pysocks]安装时用uv sync --extra socks。依赖组和可选特性容易混淆简单区分就是组是面向本地开发过程的extra 是面向库使用者的安装选项不要混用。5. 从 pip/poetry/pipenv 迁移的实操路径很多朋友不是不愿意换而是担心手里的老项目动不了。其实uv对老项目的兼容做得还可以迁移路径比我预想的平滑这里把我实际迁移的顺序和踩过的坑都列一下。5.1 迁移前盘点现状做一次冻结先把项目当前的依赖场景摸清楚。最常用的方式是把现有requirements.txt或poetry.lock里的依赖先冻结到一个临时文件作为迁移前的基准。pip freeze requirements-current.txt然后创建项目文件pyproject.toml。如果你不想手动写可以先用uv init生成一个再把name、version、requires-python等信息替换成真实的之后用uv add逐条加入直接依赖或者利用下面的兼容方式。5.2 兼容 requirements.txt 的两种用法如果你暂时不想把依赖全部迁到pyproject.tomluv 也保留了uv pip子命令兼容 pip 的经典用法uv pip install -r requirements.txt uv pip compile requirements.in -o requirements.txtuv pip compile的功能类似 pip-tools会根据requirements.in生成一份带精确版本和哈希的requirements.txt。这种模式适合“先尝鲜速度”但没有发挥 uv 最大优势我把它定位成过渡阶段。推荐的最终形态还是项目模式也就是让pyproject.toml uv.lock成为唯一真相源。实际操作中可以用uv add把老依赖逐条加进去也可以在 pyproject.toml 里写好 dependencies然后uv lock。对于依赖特别多的大项目可以考虑分轮添加每次添加一小批然后同步 测试避免一次性引入大量解析冲突。5.3 迁移时的三个关键差异容易踩坑第一依赖声明粒度不同。旧的requirements.txt里经常有githttps://...这种直接指向仓库的依赖uv 不直接支持在dependencies里这么写需要借助[project.dependency-groups]或[tool.uv.sources]语法来重写格式稍微有点不同。第二兼容性底线的设置。如果你的项目需要支持多个 Python 版本比如3.9那么 uv 解析依赖时会按最老版本3.9能兼容的方案来选择依赖的版本这很可能导致某些新版依赖被“压低”。如果你实际部署只用 3.11建议把requires-python收紧到3.11解析结果会更合理。第三私有源的配置。很多公司会用内部镜像或私有包源迁移后需要配置 uv 的索引否则默认会去官方 PyPI 解析。具体可以在pyproject.toml里配置多个索引或通过环境变量UV_INDEX_URL指定两种方式都可以我更喜欢写在项目配置里这样团队成员拉下项目后直接uv sync就能用。5.4 迁移后的验证清单完成迁移后别急着删旧文件建议按这个清单验证一遍在干净目录下重新 clone 项目执行uv sync确认环境能正常创建。执行uv run pytest确认测试通过。执行uv build确认能正常构建分发包。在 CI 中改用uv sync --frozen并跑完整流程。最后再移除 requirements 相关文件。这个顺序保证每一环都有退路不会一次性把整个工具链切死。6. 脚本运行与工具安装被忽略的“现代感”很多人用 uv 只盯着包安装但其实它在脚本运行和全局工具管理上的体验才是真正拉开差距的地方。这一节讲的都是那些“小场景”但用完之后你就很难回去了。6.1 声明式脚本脚本自带依赖免激活环境Python 一直有 PEP 723 的提议允许在脚本文件顶部用注释块直接声明依赖。uv 对这个方案的支持很到位。假设我有一个analyze.py开头可以这样写# /// script # requires-python 3.11 # dependencies [ # pandas2.0, # matplotlib3.8, # ] # /// import pandas as pd import matplotlib.pyplot as plt # ... 业务逻辑 ...然后执行uv run analyze.pyuv 会读取注释块里的依赖声明自动创建隔离的临时环境安装依赖然后运行脚本整个过程不用手动建 venv。对临时脚本、示例代码、需要分发给同事的小工具来说这个体验非常“现代”因为它把依赖声明的实体从“描述文档”变成了“可直接执行的代码的一部分”。6.2 临时环境跑一次性任务不用污染项目有时候我想比较某个库的某个 API 用法但不希望把它写进项目依赖。这时候可以用--with参数uv run --with flask --with requests2.31 python -c import flask; print(flask.__version__)它会临时创建一个环境装好列出的包然后执行后面的命令跑完即销毁不会改动项目状态。这个参数我经常用来跑一次性脚本、快速实验、复现某个 issue非常方便。6.3 全局工具安装pipx 的替代品以前装命令行工具比如ruff、black、poetry用的是pipx还得保证 pipx 自身是配置好且隔离的。uv 里直接uv tool install ruff uv tool install poetry装完可以直接执行ruff、poetry命令每个工具都运行在独立的隔离环境里互不影响。如果要更新工具uv tool upgrade ruff如果不想要了uv tool uninstall ruff这些操作都直接可用而且复用 uv 的全局缓存所以反复装工具也不会反复占用磁盘空间。7. 常见问题排查与避坑实录不管工具设计得再好现场遇到的问题永远是五花八门的。这一节整理我在实际迁移和日常使用中遇到的几个典型问题基本都能直接对应一个解决思路。7.1 uv 找不到系统 Python或想固定 Python 版本默认情况下uv会在系统 PATH 里寻找可用的 Python找不到时会根据.python-version和requires-python的约束自动下载一个下载到它自己的管理目录。但对很多团队来说希望显式固定某个版本避免有人用系统自带的 3.8 而另一个人用了 uv 自动装的 3.12。解决办法是在项目根目录维护.python-versionuv python pin 3.12这条命令会把3.12写入.python-version。共享项目时所有人uv sync都会用同一个版本如果本机没有会自动下载非常省心。如果你想优先使用某个特定路径的 Python也可以用环境变量指向它比如UV_PYTHON/usr/bin/python3.11。但这种方式适合单机配置不适合写进项目文件。7.2 网络受限或速度慢调整索引与缓存策略有时你会觉得 uv 下载依赖速度并没有宣传的那么快这通常不是 uv 本身的问题而是它默认访问官方 PyPI 在某些网络环境下速度很慢。解决思路很简单换用更快的镜像源。[tool.uv] index-url https://mirror.example.com/pypi/simple这行配置写在项目级pyproject.toml里即可。如果是在 CI 环境还可以通过环境变量UV_INDEX_URL注入不修改项目文件。另外uv 默认使用全局缓存但有时在 CI 或容器里我们更希望它少占磁盘可以用--no-cache关闭缓存或者设置UV_CACHE_DIR把缓存放到底层存储上再次运行时能复用。经验如果公司网络比较封闭离线环境可以先在一台能联网的机器上用uv sync把依赖下载好缓存目录打包同步到离线机器并设置UV_CACHE_DIR指向该目录再执行uv sync --offline体验会比用 pip 的离线包方式好不少。7.3 私有源与索引排序依赖解析出乎意料uv 支持配置多个索引比如官方源和私有源共存。但多个索引在解析时可能有优先级问题默认会优先使用配置的第一个源。如果你同时需要官方源和私有源推荐这样配置[[tool.uv.index]] name private url https://private.example.com/simple default false [tool.uv] index-strategy unsafe-first-matchdefault false表示这不是默认源只有包名在私有源中独有时才会去私有源找。index-strategy则控制解析的顺序策略。这块配置需要根据你的私有源情况微调不要盲目照抄。7.4 CI 与容器环境权限、缓存、挂载在 Docker 里用 uv 有个小坑如果缓存目录设置不当镜像层可能会变得很大每次构建都重复下载依赖。我的做法是先把pyproject.toml和uv.lockCOPY 进镜像执行一次uv sync --frozen --no-install-project这样依赖层会单独缓存后续代码变更不会触发依赖重新安装。具体实现上需要让运行目标目录先存在然后安装项目本身再分层进行。在 CI 中我很推荐缓存 uv 的缓存目录这样多次构建能大幅减少等待时间。不同 CI 平台的缓存机制不太一样但思路是一致的缓存UV_CACHE_DIR指向的目录同时确保每次构建使用相同版本 uv因为不同 uv 版本生成的 lock 格式和解析行为可能略有差异。7.5 旧工具链痕迹未清干净导致的混淆一个很容易被忽略的问题项目里残留的requirements.txt、.venv目录或virtualenv生成的激活脚本可能会让团队成员误以为项目还是旧流程。迁移时建议把旧.venv删掉让uv sync重新创建把requirements*.txt文件移入docs/或直接归档避免下次维护时看到两个依赖声明的来源。如果有 README也记得把文档里的安装步骤改成 uv 命令。实操心得迁移最忌讳的是新旧工具混用。比如用 uv sync 创建了环境又用 pip install 去装了一个包这会让环境状态与 lock 文件不一致后续uv sync会认为环境需要重新校准反而带来不必要的麻烦。环境操作入口只保留 uv才不会乱。8. 结尾的几句实在话把这一整套换下来之后我最大的感受是Python 工具链的问题不是一天形成的过去分散的解决方案虽然各自都好用但组合起来太依赖使用者自己的纪律。uv 通过一个二进制把这些事串起来之后项目的状态变得可见、可复现操作路径也短了不少。我最喜欢的几个瞬间分别是新环境一条命令跑起来的时候、CI 因为锁文件一致性问题消失的时候、脚本注释里写依赖也能运行时。当然它还在快速迭代中一些高级配置和坑也需要自己去试但作为“现代化 Python 工具”的当前优选值得每个被旧工具链折磨过的人试一次。从最简单的uv run script.py开始不需要一上来就全家桶迁移用着用着就会发现回不去了。最后再分享一个小技巧如果你的团队还没统一工具建议先在文档里把 uv 的安装命令和三个核心命令uv add、uv sync、uv run写清楚先让个人体验跑起来再推动 CI 和部署流程切换。工具链的升级最难改的往往不是代码而是习惯。但习惯一旦改了体验是真的回不去了。