uv 完整教程：下一代 Python 包管理工具

一、uv 是什么

uv 是由 Astral（Ruff 的开发团队）用 Rust 编写的 Python 包和项目管理器。它用单一工具统一替代了 pip、virtualenv、pyenv、pip-tools、pipx、poetry 等传统工具链，安装速度比 pip 快 10--100 倍 。

截至 2026 年，uv 在 PyPI 月下载量已超过 1.26 亿，成为 Python 生态中增长最快的工具。

为什么需要 uv？

传统 Python 开发需要拼凑多个工具：

pyenv 管理 Python 版本
virtualenv/venv 隔离环境
pip 安装包
pip-tools 锁定依赖
pipx 运行 CLI 工具

这些工具彼此独立，配置分散，且 pip 的依赖解析器在复杂项目下极慢。uv 将这一切合并为一个无依赖的静态二进制文件，并通过全局缓存和并行下载实现数量级的性能提升。

二、安装

官方推荐（跨平台）

bash 复制代码

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

其他方式

bash 复制代码

# Homebrew (macOS)
brew install uv

# pipx / pip
pipx install uv
pip install uv

# Docker
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

安装后验证：

bash 复制代码

uv --version
# uv 0.11.x

三、核心功能速查

传统工具	uv 替代命令	说明
`pyenv install 3.12`	`uv python install 3.12`	安装 Python 版本
`python -m venv .venv`	`uv venv`	创建虚拟环境
`pip install requests`	`uv add requests`	安装项目依赖
`pip install -r requirements.txt`	`uv pip install -r requirements.txt`	兼容模式
`pip freeze > requirements.txt`	`uv pip freeze`	导出依赖
`pipx install ruff`	`uv tool install ruff`	安装全局 CLI 工具
`poetry install`	`uv sync`	从 lock 文件同步
`poetry lock`	`uv lock`	生成锁定文件

四、从零开始：完整工作流

1. 初始化项目

bash 复制代码

uv init myproject
cd myproject

生成的结构：

复制代码

myproject/
├── .python-version      # Python 版本锁定
├── pyproject.toml       # 项目配置 + 依赖
├── uv.lock             # 精确依赖锁定（应提交 Git）
└── README.md

2. 指定 Python 版本

bash 复制代码

# 安装 Python（无需 pyenv，直接下载预编译二进制）
uv python install 3.12 3.13

# 为当前项目固定版本
uv python pin 3.12

# 查看已安装版本
uv python list --only-installed

3. 管理依赖

bash 复制代码

# 添加生产依赖（自动创建 venv，写入 pyproject.toml）
uv add fastapi uvicorn sqlalchemy

# 添加开发依赖
uv add --dev pytest ruff mypy

# 移除依赖
uv remove sqlalchemy

# 手动同步（根据 uv.lock 精确安装）
uv sync --frozen

uv.lock 是跨平台的通用锁定文件，记录每个依赖的精确版本和哈希，确保 CI 和团队协作时环境完全一致。

4. 运行代码

bash 复制代码

# 自动在项目的 venv 中运行（无需手动 activate）
uv run python main.py

# 运行模块
uv run python -m pytest

# 运行脚本（自动解析 shebang 中的依赖）
uv run main.py

5. 单文件脚本（内联依赖）

uv 支持在脚本头部直接声明依赖，无需创建完整项目：

python 复制代码

# /// script
# dependencies = ["requests", "rich"]
# ///

import requests
from rich import print

resp = requests.get("https://api.github.com")
print(resp.json())

运行：

bash 复制代码

uv run script.py
# uv 会自动创建临时环境并安装依赖

五、从现有项目迁移

从 pip + requirements.txt

bash 复制代码

# 进入现有项目
cd existing-project

# 初始化 uv（保留现有文件）
uv init

# 导入现有依赖
uv pip install -r requirements.txt

# 生成 pyproject.toml + uv.lock
# 之后可以删除 requirements.txt

从 Poetry

Poetry 使用非标准 [tool.poetry] 配置，需要手动转换或借助工具：

bash 复制代码

# 1. 备份 pyproject.toml
# 2. 将 [tool.poetry.dependencies] 迁移到 [project.dependencies]（PEP 621 格式）
# 3. 重新初始化
uv init
uv lock

六、CI/CD 与 Docker

GitHub Actions（极速示例）

yaml 复制代码

name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5

      # uv 自带 Python 管理，无需 setup-python
      - run: uv python install 3.12
      - run: uv sync --frozen
      - run: uv run pytest
      - run: uv run ruff check .

uv sync --frozen 严格按 uv.lock 安装，不做任何解析，CI 冷启动可在 8 秒 内完成，而 pip 通常需要 90 秒。

Docker 多阶段构建

dockerfile 复制代码

# 阶段 1：依赖同步
FROM python:3.12-slim AS builder
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev --no-install-project

# 阶段 2：运行
FROM python:3.12-slim
WORKDIR /app
COPY --from=builder /app/.venv /app/.venv
COPY . .

ENV PATH="/app/.venv/bin:$PATH"
CMD ["uv", "run", "gunicorn", "main:app"]

七、高级用法

1. 全局 CLI 工具（替代 pipx）

bash 复制代码

# 安装全局工具
uv tool install ruff
uv tool install black

# 临时运行（不安装）
uvx ruff check .
uvx python -c "print('hello')"

2. Workspace 多包仓库

uv 支持 Cargo 风格的工作区，适合 monorepo：

toml 复制代码

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

bash 复制代码

myrepo/
├── pyproject.toml
├── packages/
│   ├── core/
│   │   └── pyproject.toml
│   └── api/
│       └── pyproject.toml
└── uv.lock          # 整个仓库共享一个 lock

3. 依赖覆盖与可选依赖

toml 复制代码

[project.optional-dependencies]
dev = ["pytest", "ruff"]
cuda = ["torch[cuda]"]

[tool.uv.pip]
extra-index-url = ["https://download.pytorch.org/whl/cu121"]

bash 复制代码

# 安装特定可选组
uv sync --extra cuda

4. 缓存管理

bash 复制代码

uv cache dir          # 查看缓存路径
uv cache clean        # 清理缓存
uv cache prune        # 删除未使用的包

uv 使用全局内容寻址缓存，不同项目间相同包只存一份，大幅节省磁盘空间。

八、性能对比

在 GitHub Actions 上测试典型 Django + ML 项目（80 个依赖）：

工具	冷缓存	热缓存
pip + venv	~90 秒	~12 秒
Poetry 2.x	~50 秒	~3 秒
uv 1.0+	~8 秒	~0.5 秒

按每周 200 次 CI 构建计算，uv 每年可为团队节省约 58 小时 的流水线时间。

九、常见问题

Q: uv 能完全替代 conda 吗？

对于纯 Python 项目可以。若涉及 CUDA、C 库等非 Python 二进制依赖，conda 仍是首选。

Q: 生产环境稳定吗？

uv 已于 2025 年发布 1.0，Anthropic、Stripe 等大型团队已在生产 CI 中使用。

Q: 与现有 venv 兼容吗？

兼容。uv pip install --python /path/to/venv/bin/python 可直接操作现有环境。

Q: uv pip 和 uv add 有什么区别？

uv pip：pip 兼容模式，适合临时脚本或迁移期
uv add：原生项目模式，自动维护 pyproject.toml 和 uv.lock

十、总结

2026 年的 Python 工具链已经高度收敛：

uv：包管理 + 环境 + Python 版本
Ruff：lint + format（同样来自 Astral）
mypy / ty：类型检查

对于新项目，建议直接采用 uv 原生工作流（uv init → uv add → uv lock → uv sync）。对于现有 pip 项目，使用 uv pip 作为即插即用的性能升级，再逐步迁移至完整项目模式。

一句话建议 ：如果你还在用 pip install 等待进度条，现在就是切换到 uv 的最佳时机。