uv 是一个用 rust 编写的极速 python 包与环境管理器,能够一站式替代 pip、venv、pip-tools、pyenv 等传统工具,让依赖安装和虚拟环境管理的速度提升 10 到 100 倍。
本文你将了解到:
- 为什么 python 需要虚拟环境,以及传统工具链的痛点
- uv 是什么,它能替代哪些工具
- 从安装、版本管理、包管理到项目管理的完整入门教程
- 如何将已有项目迁移到 uv
如果你做 python 开发已经有段时间了,下面这些场景大概率你经历过不止一次:
- 新克隆一个项目,
pip install -r requirements.txt跑了好几分钟,你倒了杯水回来发现依赖冲突报错了。 - 在 a 项目里辛辛苦苦调通的代码,切到 b 项目就跑不起来——因为全局环境里某个包的版本被悄悄升级了。
- 用
virtualenv手动创建、激活、管理虚拟环境,步骤多到让人烦躁。
这些问题指向同一个根源:python 官方的包管理工具链(pip + venv)虽然能用,但在速度、一致性和易用性上,确实跟不上现代开发的需求了。而 uv 正是为了解决这些痛点而诞生的。

一、从虚拟环境说起:为什么我们需要隔离?
在深入 uv 之前,有必要先理解「虚拟环境」这个概念——这也是 fastapi 官方文档专门拿出一个章节来讲它的原因。
当你用 pip install 安装一个包时,它会被放到一个全局的目录里,系统中所有 python 项目都会共用这一份。比如你为项目 philosophers-stone 安装了 harry==1,后来又为项目 prisoner-of-azkaban 安装了 harry==3——后者会覆盖前者,导致第一个项目当场罢工。 fastapi
虚拟环境做的事情很简单:在每个项目里创建一个独立的目录(通常是 .venv),里面放一份专属的 python 解释器和包。激活它之后,系统会优先使用这个目录里的 python 和包,而不是全局的。激活的实质,就是把 .venv/bin(或 .venv\scripts)这个路径加到了 path 环境变量的最前面。 fastapi
正确的做法是「一个项目一个 .venv」,但传统方式下的体验并不好——创建慢、激活繁琐、跟 pyenv 各管各的、锁定依赖还得额外引入 pip-tools。而 uv 的出现,让这一切变得丝滑。

理解了虚拟环境的原理,问题就变成了:有没有一个工具能把这些散落的环节统一起来?答案就是 uv。
二、uv 是什么?它替代了哪些工具?
uv 是由 astral 团队(也是 pydantic 和 rye 的创造者)用 rust 编写的一款 python 包与项目管理工具。它的核心卖点是极致的性能和一站式的功能集成。
具体来说,uv 能替代以下工具:
| 传统工具 | 用途 | uv 中的等效命令 |
|---|---|---|
venv / virtualenv | 创建虚拟环境 | uv venv |
pip install/uninstall/list | 包安装、卸载、查看 | uv pip install/uninstall/list |
pip-tools(pip-compile / pip-sync) | 依赖锁定与环境同步 | uv pip compile / uv pip sync |
pyenv | python 版本管理 | uv python install/pin |
与此同时,uv 还提供了现代化的项目管理能力(uv init、uv add、uv sync、uv lock),让你不仅快,还能快得规范。

替代只是第一步,uv 真正让人留下来的是它的使用体验。来看它的核心优势:
三、uv 核心优势一览
- 速度快到离谱:rust 实现的依赖解析器和下载引擎,安装依赖的速度比 pip 快 10 到 100 倍。
- 二进制文件即装即用:没有 python 依赖套娃,下载一个可执行文件就能开始工作。
- 确定性构建:通过
uv.lock锁文件,确保团队成员和 ci/cd 环境安装的依赖版本完全一致。 - 兼容现有生态:完全支持
requirements.txt、pyproject.toml等标准文件格式,迁移成本极低。 - python 版本管理内置:不需要再单独安装 pyenv,uv 可以直接下载和切换 python 版本。

优势说完了,接下来进入实操。下面从安装到日常使用,手把手带你走一遍。
四、详细入门教程
4.1 安装 uv
macos / linux:
curl -lssf https://astral.sh/uv/install.sh | sh
windows(powershell):
irm https://astral.sh/uv/install.ps1 | iex
macos 也可用 homebrew:
brew install uv
安装完成后验证:
uv --version # 输出类似:uv 0.8.14 (homebrew 2025-08-28)

4.2 管理 python 版本
uv 内置了 python 版本管理功能,不需要再安装 pyenv:
# 查看可用的 python 版本 uv python list # 安装指定版本 uv python install 3.12 # 为当前项目固定 python 版本(生成 .python-version 文件) uv python pin 3.12
4.3 创建与激活虚拟环境
# 在当前目录创建名为 .venv 的虚拟环境 uv venv # 使用指定的 python 版本创建 uv venv --python 3.12 # 激活(macos / linux) source .venv/bin/activate # 激活(windows powershell) .venv\scripts\activate # 退出虚拟环境 deactivate
温馨提示:如果你用 uv run,大多数时候甚至不需要手动激活环境,uv 会自动找到正确的 .venv。
4.4 包管理(pip 兼容模式)
uv 的 uv pip 子命令与 pip 接口完全兼容,你可以无缝上手:
# 安装包 uv pip install requests # 安装特定版本 uv pip install "requests==2.31.0" # 从 requirements.txt 批量安装 uv pip install -r requirements.txt # 升级包 uv pip install --upgrade requests # 卸载 uv pip uninstall requests # 查看已安装 uv pip list # 查看依赖树 uv pip tree # 导出依赖 uv pip freeze > requirements.txt
4.5 依赖锁定与环境同步(pip-tools 模式)
这是 uv 工作流中最能体现「专业感」的两个命令。
第一步:定义顶级依赖。 创建 requirements.in,只写你项目直接用到的包:
# requirements.in fastapi uvicorn[standard] httpx
第二步:编译生成锁定文件。
uv pip compile requirements.in -o requirements.txt
这一步会递归解析整个依赖树,把每个包(包括间接依赖)的精确版本和哈希值写入 requirements.txt。
第三步:同步环境。
uv pip sync requirements.txt
uv pip sync 不仅会安装 requirements.txt 里的所有包,还会清理掉环境中多余的包,确保环境状态与锁定文件完全一致。这与 pip install -r 有本质区别——后者只安装不清理。 知乎
日常使用流程:
- 加新依赖 → 编辑
requirements.in→ 重新compile→ 重新sync - 删依赖 → 从
requirements.in移除 → 重新compile→ 重新sync
4.6 项目管理模式(推荐)
对于长期维护的项目,建议使用以 pyproject.toml 为中心的项目管理模式:
# 初始化新项目 uv init my_project cd my_project
这会生成如下结构:
my_project/ ├── pyproject.toml # 项目配置与依赖声明 ├── .python-version # 固定的 python 版本 ├── readme.md └── main.py
添加依赖:
# 生产依赖 uv add requests # 带版本约束 uv add "requests>=2.31.0" # 开发依赖(仅开发环境使用) uv add --dev pytest ruff
uv add 会自动更新 pyproject.toml 并生成 / 更新 uv.lock 锁文件。
同步环境(克隆项目后的一键安装):
uv sync
uv sync 会根据 pyproject.toml 和 uv.lock 安装所有依赖,效果类似于 pip install -r requirements.txt,但它保证环境与锁文件严格一致。如果安装慢,可以在 pyproject.toml 中配置国内镜像:
[tool.uv] index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"
移除依赖:
uv remove requests
uv add 与 uv pip install 的区别:
| 特性 | uv add | uv pip install |
|---|---|---|
| 修改配置文件 | 更新 pyproject.toml 和 uv.lock | 不修改 |
| 依赖锁定 | 确定性锁文件 | 无版本锁定 |
| 适用场景 | 长期项目、团队协作 | 临时测试、全局工具安装 |
| 虚拟环境 | 自动创建 / 同步 | 依赖手动激活 |
4.7 运行脚本(无需手动激活环境)
# 直接运行 python 脚本 uv run main.py # 运行测试 uv run pytest # 执行任意命令 uv run python -c "import requests; print(requests.__version__)"
uv run 的好处在于:不怕忘记激活环境,不怕切错 python 版本,特别适合 ci/cd 和脚本自动化场景。
4.8 典型工作流总结
如果你刚刚开始一个新项目,推荐按以下步骤来:
# 1. 初始化项目 uv init my_project && cd my_project # 2. 固定 python 版本 uv python pin 3.12 # 3. 添加依赖 uv add fastapi "uvicorn[standard]" # 4. 同步环境 uv sync # 5. 运行项目 uv run main.py
如果团队有新成员加入,他只需要:
git clone <repo> cd my_project uv sync # 一键装好所有依赖 uv run main.py # 直接运行

五、从现有项目迁移到 uv
你不需要从零开始才能用 uv。对于已有的 python 项目,迁移路径非常清晰:
5.1 只有 requirements.txt 的项目
# 进入项目目录 cd your_project # 直接用 uv 安装现有依赖,速度立竿见影 uv pip install -r requirements.txt # 如果想锁定依赖版本,一步到位 uv pip compile requirements.in -o requirements.txt uv pip sync requirements.txt
5.2 已有 pyproject.toml 的项目
cd your_project # uv 会自动识别 pyproject.toml 并生成 uv.lock uv sync # 之后所有操作都通过 uv 进行 uv add new_package uv run python main.py
5.3 从 pip + venv 迁移
# 不再需要手动创建和激活虚拟环境 # 之前:python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt # 现在: uv sync # 一条命令搞定一切
迁移的核心原则:渐进式切换。你可以在同一个项目中同时使用 pip 和 uv,逐步将 pip install 替换为 uv pip install,最后再迁移到完整的 uv sync 工作流。不用担心冲突——uv 兼容所有现有的 python 包管理标准。
六、写在最后
uv 不是要推翻 python 的包管理生态,而是用一个更快、更统一的方式,替换掉那些我们已经忍受了很久的「慢」和「散」。它兼容你已有的 requirements.txt 和 pyproject.toml,所以迁移门槛极低;它又提供了 uv.lock、uv run、uv python 这样的现代特性,值得你在下一个项目中试一试。
如果你是个人开发者,uv 能让你少花时间等安装、少踩环境不一致的坑;如果你在团队中维护项目,uv 的确定性构建会让「在我机器上能跑」这句话从日常对话里消失。
快速回顾:
uv init→ 初始化项目uv add→ 添加依赖(自动锁定)uv sync→ 一键安装所有依赖uv run→ 无需激活环境直接运行
现在打开终端,跑一个 uv --version,也许就是新习惯的开始。如果你觉得这篇文章有帮助,欢迎分享给还在用 pip install 等待的朋友——他们值得更快的体验。
到此这篇关于从pip到uv之你的python项目值得更快的包管理的文章就介绍到这了,更多相关python包管理pip到uv内容请搜索代码网以前的文章或继续浏览下面的相关文章希望大家以后多多支持代码网!
发表评论