从 pip 到 uv：你的 Python 项目值得更快的包管理

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 还提供了现代化的项目管理能力（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 的区别：

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 等待的朋友——他们值得更快的体验。