uv 教程

什么是 uv

uv 是由 Astral（即 Ruff 的作者所在公司）使用 Rust 编写的下一代 Python 包与项目管理工具。它的目标是用一个工具统一替代 pip、pip-tools、pipx、poetry、pdm、pyenv、virtualenv 等一系列工具。

uv 的核心能力可以概括为五点：

• 包管理：安装、卸载、解析、锁定依赖（兼容 pip 接口）。
• 项目管理：基于 pyproject.toml 管理项目依赖与构建，自动维护 uv.lock 锁文件。
• Python 版本管理：自动下载并管理多个 Python 解释器（替代 pyenv）。
• 虚拟环境管理：自动创建和复用虚拟环境（替代 venv/virtualenv）。
• 工具运行：类似 pipx，全局安装并隔离运行 CLI 工具。

官方文档：https://docs.astral.sh/uv/

为什么选择 uv

在了解 uv 的具体用法之前，先理解它的定位非常关键。传统 Python 工具链是「碎件化」的：

pyenv         # 管理 Python 版本
venv          # 创建虚拟环境
pip           # 安装包
pip-tools     # 锁定依赖
pipx          # 运行 CLI 工具
poetry / pdm  # 管理项目（pyproject.toml + 锁文件）
build / twine # 打包发布

uv 把上述能力整合成了一个单一可执行文件，并且在性能上做到了 10-100 倍于 pip。这也是它能在短时间内迅速流行起来的根本原因。

安装 uv

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

通过包管理器安装

# macOS
brew install uv

# Windows (Scoop)
scoop install uv

# Windows (Winget)
winget install astral-sh.uv

# 通过 pip / pipx 安装（不推荐作为主要安装方式）
pip install uv

升级与卸载

uv self update          # 自更新
uv --version            # 查看版本
# 卸载：删除 ~/.local/bin/uv 和 ~/.local/bin/uvx 即可

安装完成后，uv 与 uvx 两个命令会出现在 PATH 中。

配置镜像源（国内加速）

uv 默认从 PyPI 拉取包，国内访问较慢。配置文件位置：~/.config/uv/uv.toml（macOS/Linux）或 %APPDATA%\uv\uv.toml（Windows）。

[[index]]
url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"
default = true

# 也可使用阿里云
# [[index]]
# url = "https://mirrors.aliyun.com/pypi/simple/"
# default = true

也可以通过环境变量临时指定：

# Linux/macOS
export UV_INDEX_URL="https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"

# Windows PowerShell
$env:UV_INDEX_URL = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple"

Python 版本管理

uv 内置了 Python 版本管理能力，无需再安装 pyenv。

查看可安装的 Python 版本

uv python list

安装指定版本

uv python install 3.12        # 安装 3.12
uv python install 3.11 3.12   # 同时安装多个版本
uv python install             # 安装项目 .python-version 中指定的版本

为项目固定 Python 版本

uv python pin 3.12            # 在项目根目录生成 .python-version 文件

卸载 Python 版本

uv python uninstall 3.11

uv 会把下载的 Python 放在 ~/.local/share/uv/python 目录下，与系统 Python 完全隔离，不污染系统环境。

项目管理

uv 的项目管理工作流是其最有价值的部分，整体思路接近 Poetry / PDM，但更简洁高效。

创建新项目

uv init my-project            # 创建一个新项目
uv init my-project --lib      # 创建一个库项目（带 src 布局）
uv init my-project --app      # 创建一个应用项目（默认）

执行后会生成如下结构：

my-project/
├── .python-version    # Python 版本固定
├── README.md
├── main.py
└── pyproject.toml     # 项目配置

pyproject.toml 示例：

[project]
name = "my-project"
version = "0.1.0"
description = "Add your description here"
requires-python = ">=3.12"
dependencies = []

添加依赖

uv add requests                       # 添加最新版
uv add "requests>=2.31"               # 指定版本约束
uv add "fastapi[standard]"            # 带 extras
uv add git+https://github.com/encode/httpx  # 从 Git 安装
uv add ./my-local-pkg                 # 安装本地包
uv add --dev pytest                   # 添加到开发依赖
uv add --optional docs mkdocs         # 添加到可选依赖组

每次 uv add 都会自动更新 pyproject.toml、uv.lock 并在虚拟环境中安装。

移除依赖

uv remove requests
uv remove --dev pytest

同步依赖（核心命令）

uv sync          # 严格按照 uv.lock 安装/卸载依赖，确保环境一致
uv sync --frozen # 不更新 lock 文件，仅按 lock 安装（CI 推荐）
uv sync --dev    # 包含开发依赖（默认行为）
uv sync --no-dev # 不安装开发依赖
uv sync --all-extras  # 安装所有可选依赖

更新锁文件

uv lock                # 重新解析依赖并更新 uv.lock
uv lock --upgrade      # 升级所有依赖到允许范围内的最新版
uv lock --upgrade-package requests  # 仅升级指定包

查看依赖树

uv tree
uv tree --depth 2

运行命令（无需手动激活环境）

uv run python main.py          # 在项目环境中运行
uv run pytest                  # 运行测试
uv run ruff check              # 运行 linter
uv run --with rich python -c "import rich; rich.print('hi')"  # 临时引入 rich 运行

uv run 会自动确保虚拟环境存在且依赖已同步，是日常最常用的命令之一。

导出为 requirements.txt

uv export --format requirements-txt -o requirements.txt
uv export --no-dev -o requirements.txt   # 不含开发依赖

虚拟环境管理

虽然 uv 在项目模式下会自动管理虚拟环境，但你也可以手动操作。

uv venv                        # 在当前目录创建 .venv
uv venv my-env                 # 指定路径
uv venv --python 3.11          # 指定 Python 版本

激活方式与标准 venv 一致：

# Linux/macOS
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

实际上，在使用 uv run / uv sync 等命令时，uv 会自动使用项目下的 .venv，通常不需要手动激活。

pip 兼容接口

如果你不想使用项目管理工作流，只想用 uv 替代 pip 加速，完全没问题。uv 提供了与 pip 兼容的子命令：

uv pip install requests              # 安装包
uv pip install -r requirements.txt   # 从 requirements 安装
uv pip install -e .                  # 可编辑安装当前项目
uv pip uninstall requests            # 卸载
uv pip list                          # 列出已安装包
uv pip freeze                        # 输出 freeze 格式
uv pip compile requirements.in -o requirements.txt  # 锁定依赖（替代 pip-tools）
uv pip sync requirements.txt         # 按文件精确同步环境

这套接口与 pip / pip-tools 完全兼容，迁移成本几乎为零。

工具管理（替代 pipx）

uv 内置了 uv tool / uvx，用于全局安装并隔离运行 CLI 工具。

# 一次性运行（不安装，类似 npx）
uvx ruff check .
uvx black --version
uvx --from "git+https://github.com/psf/black" black .

# 全局安装
uv tool install ruff
uv tool install httpie

# 查看已安装工具
uv tool list

# 升级
uv tool upgrade ruff
uv tool upgrade --all

# 卸载
uv tool uninstall ruff

构建与发布

uv 集成了打包发布能力，替代 build + twine。

uv build              # 构建 sdist 和 wheel 到 dist/
uv build --wheel      # 仅构建 wheel
uv publish            # 发布到 PyPI
uv publish --token pypi-xxx   # 使用 token

多模块工作区（Workspaces）

uv 支持 monorepo 风格的工作区，类似 Cargo workspace。

# 根目录 pyproject.toml
[workspace]
members = ["packages/*"]

子包之间可通过 uv add 以本地路径方式互相依赖，uv 会统一解析、统一锁定。

# 在子包中引用同工作区的另一个包
cd packages/web
uv add my-project-core

完整工作流示例

# 1. 创建项目
uv init demo && cd demo
uv python pin 3.12

# 2. 添加依赖
uv add fastapi
uv add "uvicorn[standard]"
uv add --dev pytest ruff

# 3. 编写代码（略）后运行
uv run python main.py

# 4. 运行测试与检查
uv run pytest
uv run ruff check

# 5. 提交前同步依赖
uv sync --frozen

# 6. 构建发布
uv build
uv publish

与其他 Python 包管理工具对比

下表对比了主流 Python 包/项目管理工具的核心能力。

能力 / 工具	pip	pip-tools	poetry	pdm	conda	uv
安装包	✅	❌	✅	✅	✅	✅
依赖锁定（lockfile）	❌	✅	✅	✅	❌	✅
项目管理（pyproject.toml）	❌	❌	✅	✅	❌	✅
虚拟环境管理	❌	❌	✅	✅	✅	✅
Python 版本管理	❌	❌	❌	⚠️ 部分	❌	✅
CLI 工具运行（pipx 能力）	❌	❌	❌	❌	❌	✅
打包发布	❌	❌	✅	✅	❌	✅
工作区 / monorepo	❌	❌	⚠️ 弱	✅	❌	✅
速度（相对 pip）	1×	~1×	~1×	~1×	慢	10-100×
语言	Python	Python	Python	Python	C/Python	Rust
标准 PEP 621 兼容	⚠️ 部分	❌	⚠️ 自有	✅	❌	✅

各工具优缺点简评

pip

• 优点：官方标准，生态最广，几乎所有 Python 环境都自带；接口简单。
• 缺点：无锁文件、无项目管理、无环境管理、无版本管理；速度慢；依赖解析算法在复杂场景下偶尔出错。
• 适用：简单脚本、临时环境、CI 中从 requirements.txt 安装。

pip-tools

• 优点：在 pip 基础上补齐了依赖锁定（pip-compile / pip-sync），轻量、无侵入。
• 缺点：只解决锁定问题，不管理项目结构和环境；仍需配合 venv 使用。
• 适用：只需要锁定依赖、不想引入完整项目工具的旧项目。

poetry

• 优点：最早成熟的现代化项目管理工具，生态成熟、社区大；自带发布功能。
• 缺点：使用自有 tool.poetry 配置而非完全标准 PEP 621（新版本在改进）；速度与 pip 相当；不管理 Python 版本；对 monorepo 支持弱。
• 适用：已有大量 Poetry 项目、对生态成熟度要求高的团队。

pdm

• 优点：严格遵循 PEP 标准全家桶（PEP 517/582/621）；支持 monorepo；纯 Python 实现，可引导安装（PEP 582，无需 venv）。
• 缺点：性能与 pip 相当；生态规模不及 poetry；不直接管理 Python 解释器版本。
• 适用：偏好标准先行、注重规范化的项目。

conda

• 优点：擅长管理非 Python 依赖（如科学计算中的 C 库、CUDA、R 语言）；提供预编译二进制。
• 缺点：体积大、速度慢；与 PyPI 生态有重叠且不完全兼容；配置复杂。
• 适用：数据科学、机器学习场景，依赖大量非 Python 二进制库。

uv

• 优点：
  • 极快：Rust 实现 + 全局缓存 + 并行下载，安装速度比 pip 快一到两个数量级。
  • 一站式：一个工具覆盖版本管理、环境管理、项目管理、锁定、工具运行、构建发布。
  • 标准遵循：原生支持 PEP 621 标准 pyproject.toml，迁移成本低。
  • 兼容 pip：uv pip 子命令与 pip/pip-tools 接口兼容，可渐进迁移。
  • 跨平台：单一二进制，Windows/macOS/Linux 体验一致。
• 缺点：
  • 相对年轻：1.0 版本于 2024 年发布，部分边缘场景仍在打磨。
  • 生态依赖 Astral：单一公司主导，长期可持续性需观察（同 Ruff）。
  • 非 Python 依赖管理弱：不像 conda 能管理 C 库等系统级二进制依赖。
  • 部分高级特性文档仍在完善：工作区、构建后端等场景的边界情况需要查阅 issue。
• 适用：新项目首选；追求性能和工具链统一的中大型团队；需要管理多 Python 版本的开发者。

最佳实践

1. 新项目直接使用 uv 项目模式：uv init + uv add + uv sync + uv run，避免拼装多个工具。
2. 将 uv.lock 纳入版本控制，但 .venv 不要提交。CI 中使用 uv sync --frozen 保证可复现。
3. 用 .python-version 固定版本：uv python pin 后提交该文件，团队成员与 CI 自动使用同一版本。
4. 用 uvx 替代全局安装 CLI：避免污染系统 Python，例如 uvx ruff check 临时运行。
5. 国内环境配置镜像源：在 uv.toml 中统一配置，避免每次指定。
6. 从旧项目渐进迁移：先使用 uv pip install -r requirements.txt 享受加速，再逐步切换到 uv add 项目模式。
7. 不要在 Docker 镜像中重复安装 Python：uv 可在多阶段构建中直接拉取托管版本，显著减小镜像层。

常见问题

uv 与 poetry 的 pyproject.toml 是否兼容

uv 严格遵循 PEP 621 标准的 [project] 段，poetry 早期使用自有的 [tool.poetry] 段（新版本也支持 PEP 621）。从 poetry 迁移时，需要把依赖从 [tool.poetry.dependencies] 迁移到 [project.dependencies]，然后执行 uv lock 重新生成锁文件。

uv 是否需要单独安装 venv / pyenv

不需要。uv 内置了这两项能力。安装 uv 一个二进制即可。

uv 装的包和系统 pip 装的包会冲突吗

不会。uv 默认在项目目录下的 .venv 中工作，与系统 Python 完全隔离。使用 uv pip 时也建议指定虚拟环境，避免误操作系统环境。

CI 中如何缓存 uv

uv 的全局缓存目录默认在 ~/.cache/uv（Linux/macOS）。在 GitHub Actions 中可直接使用 actions/cache 缓存该路径，或使用官方 action astral-sh/setup-uv@v6。

总结

uv 是当前 Python 生态中最值得关注的新一代工具。它用 Rust 重写了 Python 工具链中分散的多个环节，在保持与标准（PEP 621、pip 接口）兼容的前提下，把「快」和「全」做到了极致。对于新项目，uv 已经是首选方案；对于存量项目，也可以通过 uv pip 接口渐进享受性能红利。结合本站已有的 pyenv 备忘录可以看出，uv 在大多数场景下可以一并替代 pyenv 的职责。