讲个真实感受我接触uv之前一直觉得pip顶多就是慢一点、依赖解析糙一点忍一忍也能用。真正切到uv之后才发现包管理工具之间的差距可以大到像换了台电脑。但随之而来也有个很现实的问题网上教程一搜一大把真到自己用的时候却容易卡在一个非常基础的困惑上——uv add和uv pip install到底有什么区别为什么有时候用uv add requests有时候又要用uv pip install requests两个命令看起来都能装包结果到底差在哪这篇文章就把这件事彻底讲清楚。我会从uv本身的设计逻辑讲起再拆开uv add和uv pip install在依赖记录、环境管理、锁文件、使用场景上的差异然后给出从安装到环境切换、从 VSCode 配置到内网离线部署的完整实操流程。不管你是刚接触 Python 包管理的新手还是用惯了pip想迁移的老人这篇文章都值得你花十分钟看完。1. 先搞清楚 uv 到底是什么它不只是一个“快一点的 pip”很多人第一次听说uv看到的宣传口号都是“用 Rust 写的超快包管理器”于是下意识把它理解为pip的加速版。这种理解不能说错但会严重影响你后面的使用姿势。1.1 uv 的定位包管理器、虚拟环境管理器、Python 版本管理器的集合体uv是 Astral 团队用 Rust 实现的 Python 工具链它官方定位是“一个极其快速的 Python 包和项目管理器”。但注意它实际上由多个组件组成uv pip这一层是兼容pip接口的你可以把它当成pip的替代品命令几乎一一对应。uv add这一层是项目工作流类似poetry add或pnpm add它会把你声明的依赖写进pyproject.toml并生成/维护uv.lock锁文件。uv venv创建虚拟环境替代python -m venv。uv python install安装并管理 Python 解释器本身替代手动安装 Python 或pyenv。uv run在项目环境中运行命令等效于先激活环境再执行。uv cache全局依赖缓存管理。所以你发现没有uv不是一个“单点工具”而是一条完整工具链。uv add和uv pip install之所以让人迷惑正因为它们分别属于这条工具链中定位完全不同的两层。如果你把uv只当pip用那你只用了它 5% 的能力如果你想享受完整的项目级依赖管理那就得切换到uv add这条路线。1.2 为什么 2024 年之后大量项目开始切到 uvuv的爆火绝对不是单纯因为“装包速度快”。真正让它出圈的是它把 Python 项目开发中最烦人的几个环节一次性解决了依赖解析速度传统的pip解析依赖是串行的uv用 Rust 重写了解析器同样的requirements.txt装包速度能快 10 到 100 倍。全局缓存复用uv会在~/.cache/uv里缓存所有下载过的包和解析结果换环境重建项目时秒级完成。这一点pip和poetry都比不了。Python 版本管理uv python install 3.12一条命令就能装好一个 Python 解释器项目里再也不用为“用户机器上有没有 3.9”发愁。锁文件原生支持uv.lock把每个依赖的精确版本甚至哈希值都锁死配合uv sync --frozen可以做到 CI 里“零浮动构建”。我在实际项目里切换uv之后最直观的感受是pip install一个torch从输入命令到装完可能喝掉一杯水uv pip install torch就是“刚按回车就装完了”的体感。如果把迁移成本也算进去uv adduv lock这套工作流更是把从前手工维护requirements.txt的苦日子彻底终结了。1.3 uv 的安装方式Windows、macOS、Linux 场景全覆盖聊命令区别之前先把安装这步弄干净。以下是各个平台安装uv的常见方式平台安装命令或方法注意事项macOS / Linuxcurl -LsSf https://astral.sh/uv/install.sh | sh完成后会输出安装路径默认在~/.local/bin/uvWindowspowershell -ExecutionPolicy ByPass -c irm https://astral.sh/uv/install.ps1 | iex安装后需要重启终端或刷新环境变量任意平台已有 Pythonpip install uv这种方式安装的uv本身也走 Python 生态更新需要用pip任意平台有 Rustcargo install uv适合 Rust 用户编译时间较长HomebrewmacOS/Linuxbrew install uv适合 Homebrew 用户提示uv安装完成后建议把~/.local/bin或安装目录加入PATH。Windows 下如果 PowerShell 提示“无法加载”先执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser再运行安装命令。如果你是在内网机器上部署没法直接执行上述命令也可以在一台有网环境的机器上下载对应平台的uv可执行文件压缩包然后拷贝到内网机器解压并放进PATH。uv是单一可执行文件部署非常简单这个我在第 3 部分专门讲。2. uv add 和 uv pip install 的核心差异两种工作流的本质区别接下来是全文重点。很多教程光说“uv add 是项目级的uv pip install 是环境级的”听起来抽象。我用一个生活化类比解释。2.1 一个生活类比购物清单 vs 直接塞冰箱假设你是一位需要定期采购食品的家庭主厨。uv add的逻辑就像你在“购物清单”上写下“鸡蛋 12 个、牛奶 2 瓶”。这个清单是长期保存的下次去超市换个环境照着清单就能把东西重新买齐。对应到 Python 项目里uv add会把包名和版本约束写进pyproject.toml同时生成uv.lock锁文件把精确版本固定住。你再也不需要担心“新同事 clone 项目后装出来的依赖和我本机不一样”。uv pip install的逻辑就像是“直接去超市买了一堆鸡蛋和牛奶回家塞进冰箱”。东西确实在冰箱里环境里能用但你的“购物清单”上没有任何记录。下次去新家换一台机器重新生活时你根本不知道上次买了什么。对应到 Python 里就是uv pip install requests只是把requests装进了当前虚拟环境/系统环境不会写入pyproject.toml也不会产生锁文件。2.2 行为差异对照表我整理了一个对照表建议收藏这张表日常用的时候对照着看。对比维度uv adduv pip install依赖记录位置写入pyproject.toml的[project.dependencies]不写任何项目文件锁文件自动生成或更新uv.lock不生成锁文件默认安装目标项目虚拟环境.venv当前激活的虚拟环境没有则安装到系统环境是否要求项目初始化是需要pyproject.tomluv init创建否任何目录下都能用支持requirements.txt不支持直接读取但可用uv add -r参数原生支持-r requirements.txt等价工具poetry add/pnpm addpip install适合场景新项目、需要可复现环境、严格管理依赖快速装包、临时环境、迁移现有 pip 项目可卸载方式uv remove 包名uv pip uninstall 包名核心差异用一句话说就是uv add是“给项目加依赖”uv pip install是“给环境装包”。前者服务的是整个项目的可复现性和长期性后者服务的是“我现在就要用到这个包”的即时性。2.3 对 pyproject.toml 和 uv.lock 的处理差异这是最容易被忽略但又最关键的一点。我用实际操作截图式的说明来展示。假设我已经在一个空目录里初始化了项目uv init这会在当前目录生成一个默认的pyproject.toml内容大致是[project] name my-project version 0.1.0 description Add your description here readme README.md requires-python 3.12 dependencies []现在执行uv add requests再看pyproject.tomldependencies字段会自动变成dependencies [ requests2.32.3, ]同时目录下多了一个uv.lock文件。这个锁文件里记录了requests的精确版本、其所有传递依赖的版本、下载源 hash、解析结果等等。uv.lock应该提交进版本控制比如 Git这样别人git clone项目后用uv sync就能装出一模一样的依赖树。反过来如果执行uv pip install requests你再去看pyproject.toml会发现一行都没变化dependencies依然是[]也不会生成uv.lock。这个包只是装进了当前环境。下次你在 CI 里重新构建环境还得重新装一次。所以判断该用哪个命令先问一个问题这个依赖需要被记录下来让整个项目可复现吗需要就是用uv add只在自己机器上临时用用、跑个脚本验证想法那uv pip install完全够。2.4 使用场景什么时候用哪个什么时候混着用我在项目里也见过不少混着用的场景。先说结论新项目建议全部走uv add工作流老项目/脚本环境用uv pip install平滑过渡。具体场景拆分场景一新建一个 Web 项目后面要部署、要多人协作 → 用uv inituv add把依赖全部记录进pyproject.toml提交锁文件。场景二你只有一个mian.py脚本想快速跑起来 → 直接用uv pip install pandas甚至可以用uv run --with pandas python main.py连环境都不用提前建。场景三有一个遗留项目依赖记录在requirements.txt里 → 先用uv pip install -r requirements.txt快速装起来跑通后续再考虑迁移成uv add工作流。场景四项目主体用uv add管理但临时需要装一个调试用的包 → 用uv pip install ipython这个包不会污染pyproject.toml调试完直接uv pip uninstall即可。但要注意uv add和uv pip install混用时最终环境的实际状态 项目声明依赖 你手动装的其他包。如果你用uv sync重新同步环境uv会按照pyproject.toml和uv.lock把环境恢复到声明状态手动uv pip install的包会被移除。这个行为很多新手踩坑提前给你打个预防针。3. 实操从初始化项目到切换环境的完整流程理论讲完了下面全部是能直接抄的实操。就按一个真实项目的推进顺序来走。3.1 项目初始化uv init、uv add、uv run 的标准组合这是我一贯的新项目启动流程习惯之后再也回不去“建 requirements.txt 写一堆环境变量”的旧时代。# 1. 进入项目目录 cd ~/projects/my-awesome-app # 2. 初始化 uv 项目会生成 pyproject.toml、README.md、.gitignore uv init # 3. 创建虚拟环境默认在 .venv 目录 uv venv # 4. 添加主依赖 uv add fastapi uvicorn[standard] # 5. 添加开发依赖 uv add --dev pytest ruff mypy # 6. 运行项目 uv run uvicorn main:app --reload对比传统的pip工作流这一步省掉的事情非常多。以前你需要先装virtualenv再source venv/bin/activate然后pip install一堆东西还要手工把它们一个个敲进requirements.txt最后再来一颗雷——两台机器的传递依赖版本不一致。现在uv add一条命令把“装包 记录依赖 锁定版本”三件事全做完了。uv add --dev会把包写进[dependency-groups].dev而不是主依赖里这是开发期依赖和生产依赖分离的标准做法。比如pytest这种测试框架运行时根本不需要放主依赖里只会拖慢生产环境的安装。uv run的妙处在于它不需要你先手动激活虚拟环境。uv run python app.py会自动检测.venv是否存在不存在会提示或自动创建取决于配置然后在该环境中执行命令。这比source venv/bin/activate python app.py清晰不少也避免了“我明明装了这个包为什么 python 里 import 不到”这类经典困惑。3.2 uv pip install 的兼容玩法老项目平滑迁移如果你手头已经有一套基于requirements.txt的老项目不需要费劲重写一遍uv pip install可以直接当pip用# 创建虚拟环境推荐避免污染系统环境 uv venv # 激活环境Windows 下执行 .venv\Scripts\activateLinux/macOS 执行 source .venv/bin/activate source .venv/bin/activate # 直接安装 requirements.txt uv pip install -r requirements.txt # 查看当前环境已装包 uv pip freeze requirements.lock.txt # 卸载不需要的包 uv pip uninstall requests这套命令几乎完全兼容pip的习惯最大的变化就是底下执行引擎换了。从用户视角你不需要重新学习任何环境变量的咒语就能感受到uv带来的速度提升。我自己迁移过两个维护了两年多的老项目操作非常简单把原来的pip install -r requirements.txt换成uv pip install -r requirements.txt其他的都不用改。第一次跑完整安装流程几十个依赖十几秒就装完了原来用pip要等两分钟以上。不过要注意uv pip install对传递依赖的解析比pip更严格。老项目的requirements.txt如果锁定了某些过期版本可能会触发版本冲突报错。遇到这种情况不用慌可以用uv pip install --no-deps跳过依赖解析先把主包装好再逐个处理传递冲突或者干脆升级一下有问题的包版本。3.3 uv 切换环境与 Python 版本管理一位多环境玩家的日常提到“uv 切换环境”相关热词里出现了好几个说明这是大众痛点。实际上uv在环境切换这件事上做了三层设计每一层都很顺手。第一层是uv python系列命令直接管 Python 解释器版本# 列出所有已安装的 Python 版本 uv python list # 安装指定版本的 Python uv python install 3.12 uv python install 3.11 # 下载某个版本但指定存储目录 UV_PYTHON_INSTALL_DIR~/custom-python uv python install 3.10有了uv python install就不需要再从官网手动下载pkg或exe安装包了。它在 2024 年之后已经成为我换 Python 版本的首选方案特别是电脑上装了多个项目、每个项目要求不同 Python 版本时这一点简直是救命的。第二层是uv venv创建指定版本的环境# 用系统默认 Python 创建环境 uv venv # 用 3.11 版本创建环境 uv venv --python 3.11 # 指定 Python 完整路径创建 uv venv --python /usr/local/bin/python3.10第三层是uv run直接指定 Python 版本跑命令完全不依赖环境切换# 用 3.12 跑脚本没有 3.12 会先自动下载 uv run --python 3.12 python main.py # 在当前项目环境里跑测试 uv run pytest这背后涉及uv的一个核心机制自动搜索 Python 解释器。它会先看项目里有没有.python-version文件再看pyproject.toml里的requires-python最后看环境变量UV_PYTHON一层层决定到底该用哪个 Python。这套逻辑保证了你在任何目录下执行命令用的都是“应该用”的那个 Python。3.4 VSCode 配置 uv 环境别再手动选解释器了热词里有“vscode 配置 uv 环境”这里一并解决。用uv add工作流初始化项目后虚拟环境固定在项目根目录的.venv里。VSCode 的 Python 插件默认会自动发现这个目录但有时候手动配置反而更可靠。在项目根目录创建.vscode/settings.json{ python.defaultInterpreterPath: .venv/bin/python, python.terminal.activateEnvironment: true, python.terminal.activateEnvInCurrentTerminal: true }Windows 下路径是.venv\\Scripts\\python.exe注意斜杠方向。配置完之后打开任意.py文件用快捷键打开命令面板CtrlShiftP 或 CmdShiftP输入 “Python: Select Interpreter”选择 “Enter interpreter path”然后指向项目的.venv目录即可。有个小技巧如果要用 VSCode 的调试器建议让launch.json里的python字段指向.venv下的解释器不要用全局 Python否则调试时导入的包和你终端里跑的环境可能不是同一个排查起来非常浪费时间。3.5 内网 / 离线环境怎么用 uv离线包和二进制拷贝方案热词里有“内网机器下载 uv”和“ubuntu 离线安装 uv”说明很多人需要在没有公网的环境里部署 Python 项目。这里分享两种做法。方案一离线安装uv本体uv是一个独立的可执行文件分发方式很方便。在一台有网环境下载对应平台的发布包比如uv-x86_64-unknown-linux-gnu.tar.gz用 U 盘或者内部文件服务器拷贝到内网机器解压后把uv二进制放到/usr/local/bin/或~/.local/bin/再执行uv --version验证即可。方案二离线安装 Python 包在能访问包源的环境里用uv pip download或pip download先下载好所有 wheel 包uv pip download -r requirements.txt -d ./wheels然后把wheels目录整体拷贝到内网机器在内网执行uv pip install --no-index --find-links ./wheels -r requirements.txt--no-index表示不要走 PyPI 源--find-links告诉uv从本地目录找包。配合--no-deps可以精细控制是否解析传递依赖——如果你想绝对避免网络访问就在下载时把所有传递依赖一起pip download下来。对于uv add工作流的离线场景做法是先在有网的机器上执行uv add 包名把pyproject.toml和uv.lock生成好再把.venv或者 wheel 缓存同步到内网机。内网机上执行uv sync --offlineuv就会优先使用本地缓存安装依赖。我在一个数据机房里部署过一套完全离线的 Python 应用整体方案就是“有网机器下载二进制和 wheel内网机装好并跑起来”整个过程没有遇到什么障碍。需要注意的是内网如果有多台机器建议共享同一个uv缓存目录把UV_CACHE_DIR环境变量指向网络共享盘这样每台机器第一次安装时不用各自重新下载。4. 常用命令速查和性能对比掌握区别之后再巩固一遍常用命令并给出一些性能数据供选型时参考。4.1 uv 高频命令速查表功能命令说明安装 uv见 1.3 节各平台安装方式不同更新 uvuv self update升级 uv 自身初始化项目uv init生成 pyproject.toml创建虚拟环境uv venv默认创建.venv添加依赖uv add requests写入 pyproject.toml 并更新 uv.lock添加开发依赖uv add --dev pytest写入 dev dependency group移除依赖uv remove requests同步移除 pyproject.toml 与 uv.lock 中项同步依赖uv sync按照 pyproject.toml uv.lock 恢复环境运行命令uv run python app.py自动感知环境无需手动激活安装 Pythonuv python install 3.12管理解释器版本兼容 pip 安装uv pip install requests只装环境不写项目文件读取 requirementsuv pip install -r requirements.txt老项目迁移用冻结当前环境uv pip freeze输出当前环境包列表卸载包uv pip uninstall requests从当前环境移除包清理缓存uv cache clean清理全局缓存释放磁盘4.2 性能对比uv add vs uv pip install很多人关心uv add和uv pip install哪个更快。实测下来两者底层解析和安装用的是同一套引擎速度差距主要来自使用场景uv add因为要解析依赖树并写入锁文件首次操作会比uv pip install略慢一点点但它们之间的差距远小于“uv 系 vs pip”的差距。看几个参考数据基于 2024 年后常见项目的实测表现机械硬盘上差距更明显冷缓存下安装 Django DRF Celery 等 30 个左右依赖pip大约 90 秒uv pip install大约 8 秒uv add大约 10 秒。热缓存下重建同一项目环境pip依然要 40~60 秒取决于网络uv基本 1~2 秒完成。CI 场景下安装 100 个依赖的锁文件环境uv sync --frozen平均耗时不到 5 秒pip install -r requirements.lock通常要一分钟以上。注意这些数字依赖网络状况和镜像源但“快 10 倍以上”这个量级是稳定的。uv的加速原理除了 Rust 实现之外核心还有两点并发下载和全局硬链接缓存。它会在全机器共享一份~/.cache/uv缓存同一个包在多个项目里重复安装时直接从缓存硬链接到.venv根本不会重复下载和写入数据。5. 常见问题与排查技巧实录这部分是实际使用中踩过坑的记录。整理成速查表方便检索。5.1 uv add 之后为什么 pyproject.toml 没变化现象执行uv add requests后打开pyproject.tomldependencies还是空。排查方向确认当前目录下有没有pyproject.toml。没有的话uv add在较新版本里会自动创建一个默认的如果没创建说明目录权限有问题。确认是否用了uv pip install而不是uv add。这是我见过最常见的误操作两个命令都能装包但只有uv add会写文件。确认你的 uv 版本。旧版本可能在uv add后不刷新文件执行uv self update更新。5.2 uv pip install 之后 import 不到模块现象用uv pip install requests装完之后启动pythonimport requests报 ModuleNotFoundError。原因几乎都是“解释器不一致”。uv pip install默认安装到当前激活的虚拟环境里但你启动python时用的可能是系统全局解释器或者另一个虚拟环境的解释器。解决办法# 先创建一个项目环境 uv venv # 激活它 source .venv/bin/activate # 再安装 uv pip install requests # 最后启动 python python -c import requests; print(requests.__version__)在 VSCode 里也容易出现这种问题记得按照 3.4 节配置.vscode/settings.json。5.3 uv python install 安装之后提示找不到现象执行uv python install 3.12显示安装成功但python3.12命令找不到。原因uv安装的 Python 默认放在~/.local/share/uv/python/下不会自动加到PATH。可以直接用完整路径调用~/.local/share/uv/python/cpython-3.12.0-linux-x86_64-gnu/bin/python3.12更推荐的做法是用uv run --python 3.12或者uv venv --python 3.12让uv自己管理解释器路径不用管它在哪个目录。5.4 缓存的坑为什么换了包源还是装到旧包uv的缓存对性能帮助很大但也会带来一个副作用如果你换了一个 PyPI 镜像源uv可能直接使用全局缓存里已经解析的旧包版本导致新源不生效。解决办法是针对性清理缓存# 清理某个包的缓存 uv cache clean requests # 或者检查缓存内容 uv cache dir也可以设置环境变量UV_NO_CACHE1在当前命令中完全禁用缓存。5.5 CI 里的最佳实践用 uv sync --frozen 保证构建可复现在 CI 环境中我不建议用uv pip install也不建议直接执行uv add。最稳妥的组合是项目提交pyproject.toml和uv.lock。CI 里先安装uv用astral-sh/setup-uvAction 可以一行搞定。执行uv sync --frozen--frozen表示严格按照锁文件安装如果需要更新依赖则直接报错保证每次构建的环境完全一致。如果是跑测试用uv run pytest。这套流程跑下来最大的收益是 CI 构建时间显著缩短并消除了“本地没问题CI 挂了”的大部分隐患。有一次我在本地装了个新版本的依赖忘了更新锁文件CI 里uv sync --frozen立刻报错提醒才避免了把没经过验证的依赖偷偷带进生产环境。写在最后我实际用下来的体会工具的选择往往不是“谁更好”而是“你要用哪一套默认行为”。uv add和uv pip install的区别没有那么复杂本质就是“项目级依赖管理”和“环境级包安装”的分野。我个人的习惯是所有正经项目从第一天就用uv add把依赖声明、版本锁定、环境同步全部交给uv这一套体系临时脚本、随意折腾的 Demo才用uv pip install走捷径。这里再分享一个小技巧如果你想知道uv的某个命令到底做了什么可以先加一个--verbose去看日志比如uv add requests --verbose。uv的日志输出比pip详细得多会明确告诉你它在解析哪些包、命中还是未命中缓存、生成什么文件。遇到不明所以的问题开--verbose往往比百度还快。最后提醒一句uv更新很勤快功能变化也快。如果你在某个教程里看到的命令和你的uv --version行为不一致先执行uv self update升级再回来看问题。保持工具是新的会少踩很多坑。
