查看: 121|回复: 3

uv 替代 pip 管理 Python 依赖与虚拟环境的命令实践

[复制链接]
发表于 半小时前 | 显示全部楼层 |阅读模式
传统 Python 项目里,安装依赖、创建虚拟环境、锁定版本、切换 Python 版本、运行 CLI 工具往往要分别交给 pip、venv、pip-tools、pyenv、pipx 等不同工具。工具各管一段,命令来回切换,团队协作时容易出现依赖冲突、版本不一致、requirements.txt 描述不准、换一台机器安装结果不同等问题。uv 想解决的就是这种碎片化:它由 Astral(Ruff 的开发团队)用 Rust 编写,2024 年 2 月正式发布,最初定位是高速的 Python 包安装器与依赖解析器,2024 年 8 月进一步扩展到完整项目管理、CLI 工具管理、单文件脚本以及 Python 本身的管理。

关于速度,官方早期测试给出的数据是:无缓存场景下约为 pip/pip-tools 的 8~10 倍,暖缓存场景下约为 80~115 倍。这个数字会受网络、CPU、磁盘、包类型、缓存是否命中、操作系统等因素影响,因此网上流传的“比 pip 快 100 倍”应理解为特定安装与缓存条件下的结果,而不是任何场景都固定成立。

一、安装 uv

uv 不依赖已安装的 Python 或 Rust,可通过独立安装器直接装好。Linux / macOS 使用官方脚本:
  1. curl -LsSf https://astral.sh/uv/install.sh | sh
  2. uv --version
复制代码

Windows 可用 PowerShell:
  1. powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
复制代码

也可以走 winget:
  1. winget install --id=astral-sh.uv -e
复制代码

官方还提供 Homebrew、Scoop、Docker、PyPI 等安装方式。安装后直接执行 uv,可以看到它已经是一套完整 CLI,覆盖 uv init、uv add、uv remove、uv run、uv sync、uv lock、uv export、uv tree、uv python、uv venv、uv pip、uv tool、uv build、uv publish、uv cache、uv self 等子命令。

二、初始化项目与目录结构

新项目推荐从 uv init 开始:
  1. uv init my-project
  2. cd my-project
复制代码

生成的骨架大致如下:
  1. my-project/
  2. ├── .gitignore
  3. ├── .python-version
  4. ├── README.md
  5. ├── main.py
  6. └── pyproject.toml
复制代码

其中 pyproject.toml 是现代 Python 项目的核心配置,.python-version 记录项目推荐的 Python 版本,两者加上锁文件构成团队协作的基础。

三、依赖增删:uv add 与 uv remove

过去装包是 pip install requests,再 pip freeze > requirements.txt。uv 项目的做法是:
  1. uv add requests
  2. uv add "requests>=2.30"
  3. uv add "requests==2.32.3"
  4. uv add --dev pytest
  5. uv remove requests
复制代码

uv add 会自动完成依赖解析并把结果写入项目配置,同时同步环境;带比较符的参数用于约束版本范围,== 用于固定精确版本;--dev 把包归入开发依赖。uv remove 则同时更新依赖配置和当前环境。相比手工 pip install 再 freeze,这种方式的依赖意图与实际安装结果分离得更清楚。

四、pyproject.toml 与 uv.lock 的分工

项目里通常同时存在两个文件:
  1. pyproject.toml
  2. uv.lock
复制代码

pyproject.toml 描述“我想要什么”,例如:
  1. dependencies = [
  2.     "requests>=2.30",
  3.     "fastapi>=0.100"
  4. ]
复制代码

uv.lock 描述“最终装哪些具体版本”,会记录 fastapi、requests、starlette、urllib3 等直接与间接依赖的实际版本。团队成员执行 uv sync 时,uv 依据项目配置和锁文件准备环境,从而让不同机器上的依赖结果更一致。

如果只想重新解析依赖并更新锁文件,用:
  1. uv lock
复制代码

团队开发的常见约定是把 pyproject.toml 与 uv.lock 一起提交到 Git,其他人拉取后执行 uv sync。

五、uv sync:让环境与项目定义一致

从仓库克隆项目后,传统流程是 pip install -r requirements.txt;uv 项目一般直接:
  1. git clone xxx
  2. cd project
  3. uv sync
复制代码

uv sync 的核心语义是让当前环境与项目声明的依赖保持一致,它是接手他人项目时最常用的一条命令。

六、uv run:不必手动 activate

传统方式需要先激活虚拟环境再运行:
  1. source .venv/bin/activate
  2. python main.py
复制代码

Windows 则是 .venv\Scripts\activate。使用 uv 后可以直接:
  1. uv run python main.py
  2. uv run pytest
  3. uv run ruff check .
复制代码

uv run 会依次检查项目配置、锁文件、虚拟环境、依赖和 Python 版本,准备好运行环境再执行命令。因此很多场景下不需要手动 activate,uv run 也就成了项目内执行脚本、测试、代码检查的标准入口。

七、uv python:把 Python 版本也管起来

过去管理解释器版本要靠 pyenv、conda 或官方安装器。uv 可以直接安装与切换:
  1. uv python install 3.12
  2. uv python install 3.11 3.12
  3. uv python list
  4. uv python find
  5. uv python pin 3.12
  6. uv python uninstall 3.12
复制代码

uv python install 支持一次安装多个版本,官方文档说明其支持 CPython、PyPy 等实现。uv python pin 3.12 会把版本写入项目的 .python-version,团队成员进入项目即可知道该用哪个解释器,对多项目并存的环境尤其有用。

如果仍想手动创建虚拟环境,可用:
  1. uv venv
  2. uv venv --python 3.12
复制代码

默认生成 .venv/ 目录,--python 指定解释器版本。

八、uv pip:低成本兼容传统工作流

暂时不想迁移整个项目也没关系,uv pip 提供了贴近 pip 习惯的接口:
  1. uv pip install requests
  2. uv pip uninstall requests
  3. uv pip list
  4. uv pip show requests
  5. uv pip freeze
  6. uv pip check
复制代码

需要注意,uv pip 并不是去调用系统的 pip,而是提供了一套兼容 pip 使用习惯的底层接口。迁移时可以逐条替换:pip install 换成 uv pip install,pip uninstall 换成 uv pip uninstall,pip list、pip freeze 同理,改动成本很低。

已有 requirements.txt 的项目可以:
  1. uv pip install -r requirements.txt
  2. uv pip sync requirements.txt
复制代码

两者的关键区别是:install 更接近传统安装行为;sync 会努力让环境与文件内容一致,requirements 中未列出的包可能被移除。官方文档明确说明 uv pip sync 会删除文件中未列出的包,所以在已有环境中使用前要确认影响范围。

如果项目采用 requirements.in 加编译产物的模式,可以继续沿用类似 pip-tools 的工作流:
  1. uv pip compile requirements.in -o requirements.txt
复制代码

requirements.in 中只写 fastapi、requests、pydantic 这类顶层依赖,编译后生成的 requirements.txt 会包含解析出的完整间接依赖。

九、uv tree:排查依赖从哪来

依赖变多之后,排查“为什么装了这么多包”“谁依赖了这个包”“版本冲突源自哪里”,可以用:
  1. uv tree
复制代码

输出会以树形展示顶层包与间接依赖的关系,例如 fastapi 下的 starlette、pydantic 及其下游,requests 下的 urllib3、certifi、charset-normalizer,便于快速定位依赖来源。

十、uv tool 与 uvx:隔离使用 CLI 工具

ruff、black、httpie、yt-dlp、pre-commit、cookiecutter 这类工具,过去常用 pipx 管理。uv 提供:
  1. uv tool install ruff
  2. uv tool run ruff check .
  3. uvx ruff check .
复制代码

uv tool install 把工具装到独立环境,uv tool list 查看,uv tool uninstall 卸载;uvx 可以理解为临时运行 Python CLI 工具,无需先 pip install,也不会污染当前项目环境。例如 uvx black .、uvx pytest 都可以直接执行。

十一、uv run 执行单文件脚本

uv 还能管理单文件脚本的依赖。传统写法是先 pip install requests 再 python hello.py:
  1. # hello.py
  2. import requests
  3. print(requests.get("https://example.com"))
复制代码

借助 PEP 723 内联元数据,脚本可以自行声明依赖,然后直接:
  1. uv run hello.py
复制代码

uv 会按脚本声明的依赖准备运行环境。官方 CLI 文档明确支持 uv run --script 以及 PEP 723 风格的脚本依赖管理。这类能力适合数据处理脚本、自动化脚本、爬虫、AI Demo、一次性工具和运维脚本。

十二、uv cache:速度为何随使用提升

uv 有全局缓存机制,可以查看位置和清理:
  1. uv cache dir
  2. uv cache clean
复制代码

当项目 A、B、C 都需要 requests、pydantic、numpy 时,第一次安装完成下载、构建与缓存,后续项目命中缓存即可复用,这是 uv 在重复安装场景中表现很快的重要原因。清理缓存会牺牲这部分加速效果,通常只在排查缓存异常或回收磁盘时使用。

十三、整体架构与工具定位

从命令分组可以看出 uv 的结构:Python 管理对应 uv python、uv venv;项目管理对应 uv init、uv run、uv sync、uv lock、uv tree、uv export;包管理对应 uv add、uv remove;底层还统一到 uv cache,并为传统用户保留 uv pip 的 install、compile、sync。所以 uv 不是“一个更快的 pip”,而是把多条工具链收敛到一个入口。

与 pip 相比,pip 负责装包和依赖解析,但没有虚拟环境、Python 版本管理、项目初始化、CLI 工具管理和项目运行能力,锁文件能力也较弱;uv 在这些维度上都有对应命令,并强调全局缓存。需要说明的是,pip 并未过时,它仍是 Python 官方生态中重要的基础工具,uv 的价值是在保留 pip 工作流兼容性的同时统一项目体验。

与 Poetry 相比,两者都能做项目管理、依赖管理、虚拟环境和锁文件,Poetry 更早走向完整项目管理工具,uv 的路径则是从高速安装与解析出发,逐步叠加 pip 兼容、项目管理、Python 管理、工具管理和脚本管理,强调速度、统一工具链与低迁移成本。与 Conda 相比,Conda 覆盖 Python、C/C++、CUDA、系统库和科学计算环境,在机器学习、数据科学、复杂二进制依赖场景仍有优势;uv 更偏向 FastAPI、Django、Flask、AI Agent、RAG、爬虫、自动化、Web 后端这类现代 Python 项目开发。

十四、一个真实项目的完整流程

以一个 RAG 项目为例,从零到可协作用不了几条命令:
  1. uv init rag-project
  2. cd rag-project
  3. uv python pin 3.12
  4. uv add fastapi
  5. uv add pydantic
  6. uv add openai
  7. uv add chromadb
  8. uv add --dev pytest
  9. uv add --dev ruff
  10. uv sync
  11. uv run python main.py
  12. uv run pytest
  13. uv run ruff check .
  14. uv tree
复制代码

提交到 Git 的文件包括 pyproject.toml、uv.lock、.python-version。其他成员克隆后执行:
  1. git clone xxx
  2. cd rag-project
  3. uv sync
  4. uv run python main.py
复制代码

推荐的项目结构可以把源码放入 src 目录:
  1. my-project/
  2. ├── .venv/
  3. ├── .python-version
  4. ├── pyproject.toml
  5. ├── uv.lock
  6. ├── README.md
  7. ├── src/
  8. │   └── my_project/
  9. │       ├── __init__.py
  10. │       └── main.py
  11. └── tests/
  12.     └── test_main.py
复制代码

日常操作就是 uv sync 同步、uv run python -m my_project.main 运行、uv add / uv remove 增删依赖、uv run pytest 测试、uv run ruff check . 检查。

十五、从 pip 迁移的稳妥路径

已有 requirements.txt 的老项目不建议一次性重构。可以先创建环境并沿用原文件:
  1. uv venv
  2. uv pip install -r requirements.txt
复制代码

确认项目正常运行后,再把 requirements.txt 逐步过渡到 pyproject.toml,再生成 uv.lock,最终改用 uv sync、uv run、uv add、uv remove。若项目存在特殊安装逻辑或历史包袱,应分步迁移,而不是整体替换。

十六、常用命令速查
  1. # 项目
  2. uv init
  3. uv run
  4. uv add
  5. uv remove
  6. uv sync
  7. uv lock
  8. uv tree
  9. # Python
  10. uv python list
  11. uv python install 3.12
  12. uv python find
  13. uv python pin 3.12
  14. uv python uninstall 3.12
  15. # 虚拟环境
  16. uv venv
  17. uv venv --python 3.12
  18. # pip 兼容
  19. uv pip install xxx
  20. uv pip uninstall xxx
  21. uv pip list
  22. uv pip freeze
  23. uv pip check
  24. uv pip compile
  25. uv pip sync
  26. # 工具
  27. uv tool install ruff
  28. uv tool list
  29. uv tool uninstall ruff
  30. uvx ruff
  31. # 缓存与自身
  32. uv cache dir
  33. uv cache clean
  34. uv --version
  35. uv self update
复制代码

结语

uv 最容易被看到的是速度,但真正改变工作方式的是统一:Python 版本管理、虚拟环境、包安装、依赖解析、项目管理、锁文件、CLI 工具、单文件脚本、构建发布逐步收敛到一个命令入口。对于仍在使用 pip install、python -m venv、pip freeze 的开发者,可以先从 uv pip install 体验兼容层;确认顺手后,再迁移到 uv init、uv add、uv sync、uv run、uv lock,这也是很多 Python 开发者把它称作“Python 生态里的 Cargo”的原因。
回复

使用道具 举报

发表于 半小时前 | 显示全部楼层

Re: uv 替代 pip 管理 Python 依赖与虚拟环境的命令实践

这篇整理挺系统的,把 uv 从安装、项目初始化、依赖增删到锁文件、同步、运行和 Python 版本管理串起来了,对理解现代 Python 项目结构很有帮助。尤其是 pyproject.toml 和 uv.lock 的分工讲得很清楚,团队协作时把这两个文件连同 .python-version 一起提交,别人拉下来直接 uv sync,再用 uv run 执行脚本和测试,确实能少很多环境切换的麻烦。 速度那段提醒也很客观,100 倍这种说法确实要看缓存和安装条件,不能当成固定结论。整体看下来,uv run 省去手动 activate 这点对日常开发很实用,期待后面继续聊 uv tool、uv pip 这些子命令的实践场景。
回复 支持 反对

使用道具 举报

发表于 半小时前 | 显示全部楼层

Re: uv 替代 pip 管理 Python 依赖与虚拟环境的命令实践

写得挺系统的,尤其是把 pyproject.toml 和 uv.lock 的分工讲清楚了,这点以前用 pip 的时候确实容易糊在一起,requirements.txt 既是意图又是结果,时间一长就说不清哪些是直接依赖、哪些是传递进来的。uv add 和 uv remove 这种把依赖声明和实际安装分开处理的方式,对团队协作确实更友好。 uv run 那条我感受最深。以前接手别人项目,第一步总要确认虚拟环境有没有激活、用的是不是对的解释器,Windows 和 Linux 命令还不一样,经常在这上面浪费几分钟。现在直接 uv run pytest 或者 uv run python main.py,省掉 activate 这一步,脚本和 CI 里也少一层环境判断。 uv python pin 这个设计也很实用,把版本写进 .python-version,别人拉代码就知道该用哪个解释器,不用再靠 README 里一句“请使用 Python 3.12”。多项目并行的时候尤其省心。 想请教一下,像那种已经有 requirements.txt 的老项目,是建议直接用 uv 在现有环境上操作,还是干脆用 uv init 重新组织一遍依赖?另外 uv sync 会不会在本地已经装了额外包的情况下把它们清掉,这点在从旧流程迁移时还挺让人犹豫的。整体上这篇把常用命令串得很顺,收藏了慢慢对着练。
回复 支持 反对

使用道具 举报

发表于 半小时前 | 显示全部楼层

Re: uv 替代 pip 管理 Python 依赖与虚拟环境的命令实践

这篇整理挺适合当团队上手 uv 的入门手册,重点抓得很清楚。uv 真正的价值不只是安装快,而是把依赖声明、锁文件、环境同步、脚本运行和 Python 版本管理收拢到一套命令里,减少工具来回切换带来的不一致。 几个地方讲得特别实用:pyproject.toml 说明“想要什么”,uv.lock 记录“最终装什么”,这个分工对团队协作很关键;克隆仓库后直接 uv sync 也比 pip install -r requirements.txt 更稳;uv run 免去手动 activate,日常跑脚本、测试和检查会顺手很多;uv python pin 把解释器版本写进项目,对多项目多版本并存的环境很友好。速度部分也提醒了“快 100 倍”是特定条件下的结果,没有把它说成绝对结论,比较客观。 如果后面继续写,我会想看从现有 requirements.txt 项目迁移到 uv 的最小步骤、uv pip 和项目模式分别适合什么场景,以及团队在 CI 里怎样确保严格按锁文件同步。首帖最后一句“默认生成 .venv/”似乎还没写完,可以顺手补上虚拟环境后续的用法。
回复 支持 反对

使用道具 举报

您需要登录后才可以回帖 登录 | 注册

本版积分规则

指导单位

江苏省公安厅

江苏省通信管理局

浙江省台州刑侦支队

DEFCON GROUP 86025

Hacking Group 021A

旗下站点

态势感知中心

应急响应中心

红盟安全

联系我们

官方QQ群:112851260

官方邮箱:security#ihonker.org(#改成@)

官方核心成员

关注微信公众号

Archiver|手机版|小黑屋| ( 沪ICP备2021026908号 )

GMT+8, 2026-11-18 02:35 , Processed in 0.023904 second(s), 17 queries , Gzip On, Redis On.

Powered by ihonker.com

Copyright © 2015-现在.

  • 返回顶部