cs-note/hzh/DEV/UV.md

tags, create time

tags	create time
uv python package-manager virtualenv dependency-management	2026-05-05 15:30

UV — Fast Python Package Manager

概述

UV 是 Astral（Ruff 的出品方）开发的极速 Python 包管理工具，用 Rust 编写。它同时承担 包安装器、虚拟环境管理器 和 解析器 三种角色，兼容 pip/venv/virtualenv 的工作流，但在性能上实现了数量级提升。

[!tip] 为什么选择 UV？ pip + venv + virtualenv + poetry 需要多个工具协作——每个工具职责不同、配置分散。UV 将安装包、管理虚拟环境、生成 lock 文件、管理多版本项目统一到一个 CLI 中。基准测试显示，uv pip install 比 pip 快 10~100 倍。

[!question] 思考 一个包管理工具为什么要重写为 Rust？ —— Python 生态的依赖解析和下载是 I/O 密集型任务。Rust 提供了零成本抽象和极低的运行时开销，配合并发下载能力，这正是 pip（单线程 CPython 实现）难以企及的。

核心概念

UV 与 pip/venv/poetry 的关系

graph TD
    subgraph Traditional["传统工具链"]
        P[pip — 包安装]
        V[venv/virtualenv — 虚拟环境]
        PO[poetry/pip-tools — 依赖锁定]
    end

    subgraph UVChain["UV 工具链"]
        A[uv pip — 包安装]
        B[uv venv — 虚拟环境]
        C[uv lock — 依赖锁定]
    end

    Traditional --> D["三个独立工具配置分散"]
    UVChain --> E["单一二进制零依赖"]

    classDef old fill:#fef3c7,color:#92400e
    classDef new fill:#dcfce7,color:#166534
    classDef diff fill:#dbeafe,color:#1e3a8a
    class P,V,PO old
    class A,B,C new
    class D,E diff

兼容模式 vs 原生模式

UV 支持两种使用方式：

模式	核心命令	适用场景
uv pip 兼容模式	uv pip install / uv pip compile	从 pip 迁移，完全兼容 requirements.txt
UV 原生模式	uv add / uv lock / uv run	新项目推荐，基于 pyproject.toml 现代化工作流

[!note] uv pip 与原生命令的区别

• uv pip install 安装到系统或虚拟环境中的 site-packages，行为与 pip 一致
• uv add 直接修改 pyproject.toml 中的依赖声明，并自动更新 uv.lock，适合有明确项目结构的项目
• 生产环境建议优先使用原生模式，因为 lock 文件确保所有开发者使用完全一致的依赖树

pyproject.toml 中的 UV 配置

UV 使用标准 pyproject.toml，通过 [tool.uv] 表进行专属配置：

[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "fastapi>=0.110.0",
    "httpx",
]

[tool.uv]
dev-dependencies = [
    "pytest>=8.0",
    "ruff>=0.4.0",
]

# 指定 Python 源
[[tool.uv.index]]
name = "pypi"
url = "https://pypi.org/simple/"

# 私有源（如需）
#[[tool.uv.sources]]
#my-private-pkg = { index = "internal" }

安装

操作系统安装命令

# 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"

# Homebrew / apt / scoop
brew install uv        # macOS
apt install uv         # Ubuntu（需先添加仓库）
scoop install uv       # Windows

[!tip] 验证安装 安装完成后运行 uv --version，确认版本 ≥ 0.5.0。首次运行时 UV 会自动下载所需的 Python 版本并缓存，后续启动无需等待。

虚拟环境管理

创建与管理虚拟环境

# 创建虚拟环境（默认使用 .venv 目录）
uv venv

# 指定 Python 版本（自动下载缺失版本）
uv venv --python 3.12

# 指定目标路径
uv venv ./.venv-prod

创建成功后，激活方式与传统 venv 一致：

# macOS / Linux
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

uv run — 零激活执行

# 在虚拟环境中直接运行命令，无需手动激活
uv run python main.py

# 传递参数
uv run pytest tests/ -v

# 交互式 REPL
uv run python -i

[!tip] 为什么推荐使用 uv run？ 省去了 source .venv/bin/activate 和 deactivate 的手动步骤。CI/CD、脚本调用、编辑器集成都可以通过 uv run 一次性完成——它会自行查找 .venv 或使用 pyproject.toml 中声明的环境。

包管理与依赖

原生模式：uv add / uv remove

# 添加生产依赖（写入 pyproject.toml + 更新 uv.lock）
uv add fastapi httpx

# 添加开发依赖（写入 dev-dependencies）
uv add --dev pytest ruff mypy

# 指定精确版本或范围
uv add "requests>=2.31,<3"
uv add flask==3.0.0

# 从 Git 仓库安装
uv add git+https://github.com/user/repo.git@branch

# 移除依赖
uv remove httpx

pip 兼容模式：uv pip

# 安装 requirements.txt（行为与 pip install -r 一致）
uv pip install -r requirements.txt

# 生成锁文件（类似 pip-compile）
uv pip compile requirements.in -o requirements.locked.txt

# 卸载包
uv pip uninstall requests

版本解析策略

UV 使用基于 回溯 的高性能依赖解析器（由 pubgrub 算法驱动），与 Poetry 的行为语义相同：

flowchart LR
    A["用户请求: fastapi>=0.110 + httpx"] --> B{"解析依赖树"}
    B --> C["发现冲突: A 要求 urllib3>=2, B 要求 urllib3<2"]
    C --> D["尝试替换 B 为兼容版本"]
    D -->|"解决"| E["输出唯一可行解 → uv.lock"]
    D -->|"无解"| F["报错: 不可解析"]

    classDef ok fill:#dcfce7,color:#166534
    classDef fail fill:#f99,color:#7f1d1d
    class E ok
    class F fail

Lock 文件

uv.lock 的作用

uv.lock 是 UV 的依赖锁文件，记录的是经过解析后 每一个子依赖的确切版本号（不仅是顶层依赖）。这确保了：

1. 不同机器、不同时间安装得到完全相同的依赖树
2. CI/CD 环境可复现构建结果
3. 避免 "在我机器上是好的" 问题

典型工作流

# 新增依赖（自动生成或更新 lock 文件）
uv add httpx

# 手动更新 lock 文件（不改变 pyproject.toml，只更新锁定版本到最新兼容版）
uv lock

# 安装 lock 文件中锁定的所有依赖
uv sync

# 同步但排除 dev 依赖（生产环境）
uv sync --no-dev

[!info] uv sync vs pip install -r

• uv sync 会严格对照 uv.lock 安装——移除多余的、更新过期的、安装缺失的
• pip install -r 只看 requirements.txt，不会主动清理已安装但未声明的包
• 推荐始终使用 uv sync 代替 pip install -e .

多项目工作区（Workspace）

UV 支持 Monorepo 风格的多项目组织：

# pyproject.toml at workspace root
[project]
name = "workspace-root"
version = "0.1.0"
requires-python = ">=3.11"

[tool.uv.workspace]
members = ["packages/*"]
optional-groups = ["docs"]

# packages/web/pyproject.toml
[project]
name = "web-service"
dependencies = ["shared-lib"]  # 引用 workspace 内的其他项目

# packages/lib/pyproject.toml
[project]
name = "shared-lib"

# 在工作区根目录操作
uv lock          # 解析整个工作区的依赖
uv sync          # 安装所有成员包的依赖
uv add -p web-service fastapi   # 只为特定成员添加依赖

实战示例

创建一个 FastAPI 项目

# ① 创建项目并初始化 venv
uv init my-api
cd my-api
uv venv --python 3.12

# ② 添加依赖
uv add fastapi uvicorn httpx
uv add --dev ruff pytest

# ③ 运行项目
uv run uvicorn main:app --reload

# ④ 运行测试
uv run pytest tests/ -v

CI/CD 流水线集成

# .github/workflows/ci.yml（简化版）
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install UV
        run: curl -LsSf https://astral.sh/uv/install.sh | sh

      - name: Sync dependencies
        run: uv sync --all-extras --frozen

      - name: Run tests
        run: uv run pytest tests/ -v

      - name: Lint
        run: uv run ruff check .

[!warning] --frozen 标志的含义 加上 --frozen 时，如果 uv.lock 不存在或与 pyproject.toml 不一致，命令会直接失败而非自动更新。这在 CI 中很重要——确保 lock 文件的变更必须经过代码审查提交。

常用命令速查

命令	说明	等价命令
uv add <pkg>	添加依赖到 pyproject.toml	uv pip install
uv remove <pkg>	从依赖中移除	uv pip uninstall
uv sync	按 lock 文件同步环境	pip install -e .
uv lock	生成/更新 lock 文件	poetry lock
uv run <cmd>	在环境内执行命令	source .venv/bin/activate && cmd
uv venv	创建虚拟环境	python -m venv .venv
uv python list	列出可安装的 Python 版本	pyenv versions
uv python install 3.12	下载并缓存指定 Python	pyenv install 3.12
uv pin 3.11	锁定项目 Python 版本	设置 .python-version
uv export	导出为 requirements.txt	pip freeze > req.txt

与其他工具的对比

维度	pip + venv	Poetry	uv
语言	Python	Python	Rust
安装速度	慢（单线程）	中等	⚡ 极快（并发）
虚拟环境	venv 独立命令	poetry env	uv venv 内置
Lock 文件	需 pip-compile	poetry.lock	uv.lock
pyproject.toml	第三方支持	✅ 原生	✅ 原生
多项目/Workspace	❌	✅	✅
Python 版本管理	❌ 需 pyenv	❌ 需 pyenv	✅ uv python install
依赖大小	无额外依赖	较重	单个二进制 ~15MB
成熟度	事实标准	高	快速迭代中

[!info] 迁移建议

• pip 用户 → 直接使用 uv pip 命令获得加速，零迁移成本
• Poetry 用户 → uv 的 add/sync/lock 工作流与 Poetry 高度相似，学习曲线平缓
• 新项目 → 直接用 uv 原生命令 + pyproject.toml + uv.lock

关联笔记

• hzh/DEV/Husky — Git Hooks 管理（可与 uv run 结合在 pre-commit 中运行 lint）