02-uv包管理器
uv 是用 Rust 编写的极快 Python 包和项目管理器，由 Astral（Ruff 的创作者）开发。
它比 pip 快 10-100 倍，一个工具替代 pip、pip-tools、pipx、poetry、pyenv、virtualenv。
安装
bash
# 官方独立安装器（推荐）
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# 通过 pip 安装
pip install uv
# 通过 pipx 安装
pipx install uv
# 自我更新（仅独立安装器）
uv self update项目管理
创建项目
bash
# 初始化新项目
uv init my-project
cd my-project
# 指定 Python 版本
uv init my-project --python 3.12版本选择策略： 如果不指定版本，uv 按以下顺序决定：
- 系统 Python：使用
PATH中最新的已安装版本。- 配置文件：如果存在
.python-version，优先使用其中指定的版本。- 自动下载：若未找到合适的，自动下载最新的 CPython 版本。
项目结构
my-project/
├── pyproject.toml # 项目配置和依赖（PEP 621 标准）
├── uv.lock # 通用锁定文件（跨平台）
├── .python-version # Python 版本固定
├── .venv/ # 虚拟环境
└── src/
└── my_project/
└── __init__.py依赖管理
bash
# 添加普通依赖（自动添加版本约束）
uv add requests # 添加 requests>=x.y.z
uv add "httpx>=0.20" # 手动指定约束
# 添加开发依赖
uv add --dev pytest ruff # 添加到 dev 组
# 添加可选依赖（extras）
uv add --optional database sqlalchemy
# 使用分组管理开发依赖
uv add --group lint ruff
uv add --group test pytest
# 移除依赖
uv remove requests
uv remove --dev pytestpyproject.toml 中的依赖字段：
toml
[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = ["requests>=2.31.0"]
[project.optional-dependencies]
database = ["sqlalchemy>=2.0"]
[dependency-groups]
dev = ["pytest>=8.0"]
lint = ["ruff>=0.3"]依赖源
uv 支持从多种来源安装依赖：
bash
# 从 Git 仓库安装
uv add git+https://github.com/encode/httpx
uv add git+https://github.com/encode/httpx --tag 0.27.0
uv add git+https://github.com/encode/httpx --branch main
uv add git+https://github.com/encode/httpx --rev abc1234
# 从本地路径安装
uv add ./packages/foo
uv add --editable ../projects/bar # 可编辑安装
# 从 URL 安装
uv add "https://files.pythonhosted.org/.../httpx-0.27.0.tar.gz"
# 从指定索引安装
uv add torch --index pytorch=https://download.pytorch.org/whl/cpu对应的 pyproject.toml：
toml
[project]
dependencies = ["httpx", "foo", "bar", "torch"]
[tool.uv.sources]
httpx = { git = "https://github.com/encode/httpx", tag = "0.27.0" }
foo = { path = "./packages/foo" }
bar = { path = "../projects/bar", editable = true }
torch = { index = "pytorch" }
[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cpu"平台特定依赖
bash
# 仅在 Linux 安装
uv add "jax; sys_platform == 'linux'"
# 仅在 Python 3.11+ 安装
uv add "numpy; python_version >= '3.11'"运行与同步
bash
# 运行命令（自动创建环境并安装依赖）
uv run python main.py
uv run ruff check .
# 指定 Python 版本运行
uv run --python 3.11 python main.py
# 锁定依赖
uv lock
# 同步环境
uv sync
uv sync --all-groups # 包含所有依赖组
uv sync --no-dev # 不包含开发依赖脚本运行
uv 支持 PEP 723 内联脚本元数据，无需手动管理环境：
bash
# 创建带元数据的脚本
uv init --script example.py --python 3.12
# 为脚本添加依赖
uv add --script example.py requests rich
# 运行脚本（自动创建临时环境）
uv run example.py
# 指定依赖运行（无需修改脚本）
uv run --with rich example.py
uv run --with 'rich>12,<13' example.py
# 锁定脚本依赖
uv lock --script example.py脚本文件格式：
python
# /// script
# requires-python = ">=3.12"
# dependencies = [
# "requests<3",
# "rich",
# ]
# ///
import requests
from rich.pretty import pprint
resp = requests.get("https://example.com")
pprint(resp.json())使用 shebang 创建可执行脚本：
python
#!/usr/bin/env -S uv run --script
# /// script
# dependencies = ["httpx"]
# ///
import httpx
print(httpx.get("https://example.com"))bash
chmod +x greet
./greet工具管理
类似 pipx，用于安装 CLI 工具：
bash
# 临时运行工具（隔离环境）
uvx ruff check .
uvx pycowsay 'hello world!'
# 指定版本
uvx ruff@0.5.0 check .
uvx ruff@latest check .
# 从指定包运行命令
uvx --from httpie http
# 安装工具到 PATH
uv tool install ruff
uv tool install 'httpie>0.1.0'
# 安装工具并添加额外依赖
uv tool install mkdocs --with mkdocs-material
# 升级工具
uv tool upgrade ruff
uv tool upgrade --all
# 指定 Python 版本
uvx --python 3.10 ruffPython 版本管理
uv 内置 Python 版本管理，无需 pyenv：
bash
# 安装 Python
uv python install 3.12 3.13
uv python install pypy
# 查看可用版本
uv python list
uv python list --only-installed
# 固定项目 Python 版本
uv python pin 3.11 # 创建 .python-version
# 查找 Python 解释器
uv python find
uv python find '>=3.11'
# 升级 Python（补丁版本）
uv python upgrade 3.12
uv python upgrade # 升级所有
# 卸载 Python
uv python uninstall 3.12支持 CPython、PyPy、Pyodide、GraalPy，自动下载安装。
工作区
类似 Cargo workspace，管理多包项目：
toml
# 根 pyproject.toml
[project]
name = "my-workspace"
version = "0.1.0"
[tool.uv.workspace]
members = ["packages/*"]my-workspace/
├── pyproject.toml
├── uv.lock
└── packages/
├── core/
│ └── pyproject.toml
└── utils/
└── pyproject.toml工作区成员默认以可编辑模式安装：
bash
uv add --dev pytest # 添加到根项目pip 兼容接口
兼容现有 pip 工作流，性能提升 10-100 倍：
bash
# 创建虚拟环境
uv venv
uv venv --python 3.12
# 激活环境
source .venv/bin/activate
# 编译依赖（类似 pip-compile）
uv pip compile requirements.in -o requirements.txt
uv pip compile requirements.in --universal -o requirements.txt
# 同步环境（类似 pip-sync）
uv pip sync requirements.txt
# 安装包
uv pip install requests
uv pip install -r requirements.txt
# 查看已安装
uv pip list
uv pip freeze配置
uv 配置文件 ~/.config/uv/uv.toml 或项目 pyproject.toml：
toml
[tool.uv]
# 默认依赖组
default-groups = ["dev", "lint"]
# Python 下载策略
python-downloads = "automatic" # 自动下载（默认）
python-downloads = "manual" # 仅手动安装
# Python 偏好
python-preference = "managed" # 优先 uv 管理的 Python
python-preference = "system" # 优先系统 Python
# 包索引
[[tool.uv.index]]
name = "tsinghua"
url = "https://pypi.tuna.tsinghua.edu.cn/simple"包管理器对比
| 特性 | pip | uv | conda |
|---|---|---|---|
| 速度 | 慢 | 极快 | 中等 |
| 虚拟环境 | 需配合 venv | 内置 | 内置 |
| 非 Python 包 | ❌ | ❌ | ✅ |
| Python 管理 | ❌ | ✅ | ✅ |
| 工具管理 | ❌ | ✅ | ❌ |
| 脚本元数据 | ❌ | ✅ (PEP 723) | ❌ |
| 锁定文件 | pip-tools | 内置 | environment.yml |
| 工作区 | ❌ | ✅ | ❌ |
本章小结
┌─────────────────────────────────────────────────────────────┐
│ uv 包管理器 知识要点 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 核心功能： │
│ ✓ 项目管理 - uv init/add/run/lock/sync │
│ ✓ 脚本运行 - PEP 723 内联元数据 │
│ ✓ 工具管理 - uvx / uv tool install │
│ ✓ Python 管理 - uv python install/list/pin │
│ ✓ 工作区 - Cargo 风格多包管理 │
│ │
│ 依赖管理： │
│ ✓ 普通依赖、开发依赖、可选依赖、依赖分组 │
│ ✓ 多种来源：PyPI、Git、URL、本地路径、自定义索引 │
│ ✓ 平台特定依赖、可编辑安装 │
│ │
│ 优势： │
│ ✓ 10-100x 比 pip 快 │
│ ✓ 一个工具替代多个工具 │
│ ✓ 全局缓存去重，磁盘高效 │
│ ✓ 兼容现有 pip 工作流 │
│ │
└─────────────────────────────────────────────────────────────┘