uv：Python 包管理的快速工具 – 孙成新的个人博客

uv 是由 Astral 公司开发的 Python 包管理器，使用 Rust 编写，专注于速度和简洁性。它可以作为 pip、pip-tools、virtualenv 和 Poetry 的高效替代品，支持依赖解析、虚拟环境管理、锁文件生成和脚本执行等功能。uv 的核心优势是 10-100 倍的性能提升，尤其适合大型项目。截至 2025 年 10 月，uv 已支持平台无关的解析、依赖版本覆盖和可重现构建等高级特性。

以下是详细的使用指南，按步骤展开。假设你已在终端中操作，所有命令基于 uv 最新版本（0.5+）。

1. 安装 uv

uv 支持多种安装方式。最简单的是使用官方安装脚本：

Linux/macOS：

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

Windows (PowerShell)：

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

其他方式包括：

通过 pip：pip install uv
Homebrew（macOS）：brew install uv
更多方法见官方文档：https://docs.astral.sh/uv/getting-started/installation/

安装后，验证：uv --version。uv 会自动添加到 PATH 中。

2. 创建项目和虚拟环境

uv 强调项目驱动的工作流。它会自动管理虚拟环境（默认在 .venv 目录）。

初始化新项目：

  uv init myproject  # 创建名为 myproject 的项目目录
  cd myproject

这会生成 pyproject.toml 文件（用于声明依赖）和 .venv 虚拟环境。

手动创建虚拟环境：

  uv venv  # 使用当前 Python 版本创建 .venv

或指定 Python 版本：

  uv venv --python 3.12.0  # 使用 CPython 3.12.0

激活环境：

  source .venv/bin/activate  # Linux/macOS
  .venv\Scripts\activate     # Windows

uv 支持安装多个 Python 版本：uv python install 3.11 3.12。

固定 Python 版本（最佳实践）：

  uv python pin 3.12  # 在项目中固定 Python 3.12

3. 添加和安装依赖

uv 使用 pyproject.toml 声明依赖，支持开发依赖（dev）和可选依赖（optional）。

添加依赖：

  uv add requests  # 添加运行时依赖，自动更新 pyproject.toml 并安装
  uv add --dev pytest  # 添加开发依赖（如测试工具）
  uv add --optional docs sphinx  # 添加可选组（如文档工具）

从 requirements.txt 安装（兼容 pip）：

  uv pip install -r requirements.txt

为脚本添加依赖（内联元数据支持）：
如果有独立脚本（如 script.py），uv 可以直接为其管理依赖：

  echo 'import requests; print(requests.get("https://astral.sh"))' > script.py
  uv add --script script.py requests  # 更新脚本元数据并安装

uv 的 uv pip 子命令是 pip 的增强版，支持更快解析和通用 wheel 文件：

uv pip install numpy --upgrade

4. 锁定依赖（uv.lock）

锁文件 uv.lock 记录精确的依赖版本和哈希，确保跨环境可重现安装（类似于 poetry.lock）。

生成/更新锁文件：

  uv lock  # 解析依赖并生成 uv.lock

同步环境（安装锁定的依赖）：

  uv sync  # 审计并安装缺失包，移除多余包
  uv sync --dev  # 包括开发依赖
  uv sync --group docs  # 只同步特定组

从锁文件导出（可选）：

  uv export > requirements.txt  # 生成 requirements.txt

注意：uv.lock 是 TOML 格式，便于版本控制。每次添加/移除依赖后，运行 uv lock 更新它。

5. 运行脚本和工具

uv 支持在隔离环境中运行脚本，无需手动激活环境。

运行项目脚本：

  uv run script.py  # 自动使用 .venv，安装依赖后执行
  uv run python -m mymodule  # 运行模块

运行工具（类似于 pipx）：

  uvx ruff check .  # 在临时环境中运行 ruff，无需全局安装

工作区支持（多包项目）：
对于 monorepo，uv 支持工作区：

  uv workspace add subpackage  # 添加子包
  uv sync --all  # 同步所有工作区

6. 其他常用命令

使用表格总结关键命令：

命令	描述	示例
`uv init <name>`	初始化项目	`uv init myapp`
`uv add <pkg>`	添加并安装依赖	`uv add flask --dev black`
`uv remove <pkg>`	移除依赖	`uv remove requests`
`uv lock`	生成/更新 uv.lock	`uv lock`
`uv sync`	同步环境到锁文件	`uv sync --frozen` (不更新锁文件)
`uv run <cmd>`	运行命令/脚本	`uv run pytest`
`uv venv`	创建虚拟环境	`uv venv --python 3.11`
`uv pip compile`	编译 requirements（类似于 pip-tools）	`uv pip compile pyproject.toml`
`uv pip sync`	从 requirements 同步安装	`uv pip sync requirements.txt`
`uv tool install`	安装全局工具	`uv tool install ruff`
`uv cache clean`	清理缓存	`uv cache clean`

7. 最佳实践

项目结构：始终使用 pyproject.toml 声明依赖，避免 requirements.txt（除非兼容旧项目）。
可重现性：提交 pyproject.toml 和 uv.lock 到 Git；CI/CD 中运行 uv sync --frozen。
性能优化：uv 默认使用并行下载和缓存；对于大型项目，启用 --no-cache 测试干净安装。
迁移：
从 pip：直接用 uv pip install 替换。
从 Poetry：uvx migrate-to-uv uv init-from poetry 导入，然后 uv sync。
常见问题：uv 不支持某些旧包的源安装（fallback 到 pip）；确保 Python 版本兼容。
高级功能：支持依赖覆盖（uv add --override）、平台特定依赖和 Git 依赖（uv add git+https://github.com/user/repo）。

与 pip 和 Poetry 的区别

vs. pip：uv 更快，支持锁文件和项目管理；uv pip 是 pip 的 drop-in 替换，但添加了可重现解析和内联脚本支持。
vs. Poetry：uv 更轻量、速度更快，但 Poetry 在发布和构建上更完整。uv.lock 和 poetry.lock 不可互换，但 uv 支持从 Poetry 迁移。
uv 更适合现代工作流，如与 Ruff（代码检查）结合。