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

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

UV 旨在取代多种传统工具（如 pip、pip-tools、pipx、Poetry、pyenv、Twine 和 virtualenv）。它支持 macOS、Linux 和 Windows 平台，可通过 curl 或 pip 安装，无需 Rust 或 Python 环境。其核心优势包括：

速度极快：比 pip 快 10-100 倍，通过全局缓存实现依赖去重，节省磁盘空间。
统一工具：单一二进制文件处理包安装、项目管理、虚拟环境创建、Python 版本管理和工具执行。
与传统工具比较：
取代 pip：通过 uv pip 提供兼容接口，支持依赖覆盖和可重现解析。
超越 Poetry：支持锁文件（uv.lock）、工作区和依赖解析。
整合 pipx：使用 uvx 运行临时工具，uv tool install 持久安装工具。
无需 pyenv/virtualenv：直接管理 Python 版本和虚拟环境。
主要功能：项目依赖管理（添加、锁定、同步）、脚本运行（支持内联依赖元数据）、Python 版本安装/固定、工具安装/执行，以及要求文件编译/导出。

UV 的核心工作流：uv init（初始化项目）→ uv add（添加依赖）→ uv lock（锁定依赖）→ uv sync（同步环境）→ uv run（运行脚本）。以下是详细的使用指南，按步骤展开。假设你已在终端中操作，所有命令基于 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. 常用命令

Python UV 项目管理工具介绍

UV 的核心工作流：uv init（初始化项目）→ uv add（添加依赖）→ uv lock（锁定依赖）→ uv sync（同步环境）→ uv run（运行脚本）。

UV 主要命令及用法

以下是 UV 的主要 CLI 命令，按功能分组整理。命令使用英文原名，附带简要描述和常见用法示例（基于官方文档）。

1. 项目与依赖管理

命令	描述	常见用法示例
uv init	创建新 Python 项目，生成 `pyproject.toml` 文件，支持应用、库或脚本类型。	`uv init myproject` `uv init --lib mylib` `uv init --app myapp`
uv add	添加包到 `pyproject.toml`，更新 `uv.lock`，并（除非 `--no-sync`）安装到虚拟环境。支持开发组、额外依赖和 requirements 文件。	`uv add requests` `uv add ruff --dev` `uv add -r requirements.txt`
uv remove	从 `pyproject.toml` 移除包，更新锁文件和环境（除非 `--no-sync`）。	`uv remove requests` `uv remove ruff --dev`
uv lock	重新生成/更新 `uv.lock` 文件以匹配 `pyproject.toml`。	`uv lock` `uv lock --upgrade`
uv sync	安装/更新虚拟环境以匹配 `uv.lock`。	`uv sync` `uv sync --extra docs`
uv export	导出锁定的依赖图到其他格式（如 requirements.txt、JSON）。支持过滤组、额外依赖。	`uv export -f requirements.txt` `uv export --no-dev -o requirements.txt`

2. 运行代码与脚本

命令	描述	常见用法示例
uv run	在隔离环境中执行命令、脚本或模块，支持内联依赖元数据（PEP 723）。	`uv run python script.py` `uv run --with requests my_script.py`

3. 虚拟环境管理

命令	描述	常见用法示例
uv venv	创建虚拟环境（可选自定义路径或种子包）。	`uv venv` `uv venv myenv --seed`

4. Python 版本管理 (`uv python`)

子命令	描述	常见用法示例
uv python install	下载并安装特定 Python 版本（CPython/PyPy）。	`uv python install 3.12` `uv python install 3.13 --default`
uv python pin	通过 `.python-version` 文件固定项目（或全局）Python 版本。	`uv python pin 3.12`

5. 工具管理 (`uv tool`)

子命令	描述	常见用法示例
uv tool install	安装 CLI 工具到管理环境。	`uv tool install black` `uv tool install --upgrade black`
uv tool list	列出已安装工具及其版本/环境信息。	`uv tool list`

6. 构建与发布

命令	描述	常见用法示例
uv build	从包目录构建源分发（sdist）和/或 wheel。	`uv build` `uv build --wheel`
uv publish	上传构建的分发到包索引（如 PyPI）。	`uv publish` `uv publish --dry-run`

7. 缓存与自管理

子命令	描述	常见用法示例
uv cache clean	移除缓存条目（可选特定包）。	`uv cache clean requests`
uv self update	更新 UV 二进制到最新版本。	`uv self update`

通用标志（适用于多数命令）：--project <dir>（指定项目根目录）、--offline（离线模式）、--quiet（静默输出）、--upgrade（允许升级）等。更多细节可参考官方文档：https://docs.astral.sh/uv/reference/cli/。

根据附件介绍一般项目主要的通用依赖包

附件 pyproject.toml 是 UV 配置的典型 Python 项目文件（名为 “cooley”，版本 0.1.0），定义了项目元数据、依赖和工具配置。它使用了 UV 的特性，如 [dependency-groups]（开发组）、[tool.uv]（依赖覆盖和本地源）和自定义索引源。以下是项目中主要的通用依赖包介绍，按类型分组。这些依赖适用于一个涉及自动化测试、Google API 集成、浏览器自动化和重试机制的通用 Web/自动化项目：

核心运行时依赖（[project.dependencies]）

这些是项目运行必需的包：

agentql：自动化查询和测试工具，常用于 UI 测试和数据提取。
python-dotenv：加载 .env 文件中的环境变量，支持安全配置管理。
pytz：时区处理库，用于跨时区日期时间操作。
tenacity：重试装饰器库，用于实现故障恢复和指数退避重试机制。
oauth2client (4.1.3 <= v < 5.0.0)：Google OAuth 2.0 客户端，支持身份验证和令牌管理。
google-api-python-client (2.172.0 <= v < 3.0.0)：Google API Python 客户端，用于访问 Google 服务（如 Sheets、Drive）。
playwright (==1.50.0)：浏览器自动化库，支持 headless 测试和 Web 抓取（UV 覆盖了此版本以确保兼容）。

开发依赖（[dependency-groups.dev]）

这些是开发、测试和代码质量工具：

pytest：测试框架，用于编写和运行单元/集成测试。
pytest-asyncio：pytest 插件，支持异步测试。
pyright：Microsoft 的静态类型检查器，类似于 mypy。
isort：Python 导入排序工具，确保代码风格一致。
black：代码格式化器，自动格式化 Python 代码。

这些依赖体现了 UV 在项目中的应用：通过 pyproject.toml 声明依赖，支持开发组隔离、uv.lock 锁定版本，以及本地源（如 “common”）的 editable 安装。典型用法：在项目根目录运行 uv sync 安装所有依赖，uv add <pkg> 添加新包。

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（代码检查）结合。