uv: Python 工具链的革命性突破

引言

Python 生态系统迎来了一个新标准，它叫做 uv。由 Ruff 的创造者 Astral 团队开发，uv 是一个用 Rust 编写的"Python 版 Cargo"，代表着 Python 工具链的巨大飞跃。

它不仅仅是"更快的 pip"。uv 是一个单一、统一的工具，旨在替代整个工具集合：pip、pip-tools、venv、virtualenv、pipx、bump2version、build 和 twine。

性能提升令人震惊（通常快 10-100 倍），但真正的价值在于统一的工作流程。

为什么现在大家都在用 uv？

1. 性能革命：10-100x 的速度提升

uv 使用 Rust 编写，带来了原生性能优势：

并行操作：依赖解析和安装完全并行化
全局缓存：依赖在所有项目间共享，节省数 GB 磁盘空间
极速环境创建：新虚拟环境几乎瞬间完成

实际对比：

1
2
3
4
5
# pip 安装 Django 及其依赖：~15 秒
pip install django

# uv 安装相同包：~0.5 秒
uv pip install django

2. 统一工作流：一个工具完成所有任务

过去，Python 开发需要多个工具：

依赖管理：pip、pip-tools
虚拟环境：venv、virtualenv
全局工具：pipx
构建和发布：build、twine
版本管理：bump2version

现在，uv 一个工具就够了。

3. Python 版本管理

uv 内置 Python 版本管理，无需 pyenv 或其他工具：

1
2
3
4
5
6
7
8
# 安装 Python 版本
uv python install 3.12

# 列出可用版本
uv python list

# 设置项目 Python 版本
uv python pin 3.12

4. 全局缓存：节省空间和时间

uv 使用智能的全局缓存系统：

跨项目共享依赖：相同版本的包只下载一次
节省磁盘空间：避免重复存储相同的包
加速新项目：复用已缓存的依赖

uv 带来的核心好处

✅ 简化工具栈

从多个工具精简到一个，减少认知负担和配置复杂度。

✅ 极速性能

依赖解析、安装、环境创建都快如闪电。

✅ 统一体验

从项目初始化到发布的完整生命周期，体验一致。

✅ 现代化依赖管理

自动锁文件（uv.lock）、精确的依赖解析、可复现的构建。

✅ 开发体验优化

更少的等待时间意味着更多的编码时间，更快的反馈循环。

完整项目生命周期管理

uv 的真正威力在于它处理项目的整个生命周期：

1️⃣ 项目初始化

1
2
3
4
5
6
7
8
9
# 创建新项目
uv init my-project
cd my-project

# 项目结构自动生成
# ├── pyproject.toml
# ├── README.md
# ├── .gitignore
# └── .python-version

2️⃣ 依赖管理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# 添加依赖
uv add requests fastapi "uvicorn[standard]"

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

# 移除依赖
uv remove requests

# 同步依赖（安装 lock 文件中的所有依赖）
uv sync

# 更新依赖
uv lock --upgrade

3️⃣ 虚拟环境管理

1
2
3
4
5
6
7
8
9
# uv 自动管理虚拟环境，但你也可以手动操作
uv venv

# 在虚拟环境中运行命令
uv run python script.py
uv run pytest

# 激活虚拟环境（传统方式，可选）
source .venv/bin/activate

4️⃣ 版本管理

1
2
3
4
# 升级版本
uv version --bump patch  # 0.1.0 -> 0.1.1
uv version --bump minor  # 0.1.1 -> 0.2.0
uv version --bump major  # 0.2.0 -> 1.0.0

5️⃣ 构建和发布

1
2
3
4
5
6
7
8
# 构建项目
uv build

# 发布到 PyPI
uv publish

# 发布到测试 PyPI
uv publish --publish-url https://test.pypi.org/legacy/

工具和脚本管理

uv 不仅仅管理项目依赖，还能替代 pipx 和 pip-run：

全局工具安装

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# 安装全局工具（隔离环境）
uv tool install ruff
uv tool install black
uv tool install httpie

# 列出已安装的工具
uv tool list

# 更新工具
uv tool upgrade ruff

# 卸载工具
uv tool uninstall ruff

脚本执行

uv 可以运行脚本并自动管理其依赖：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# script.py
# /// script
# dependencies = [
#   "requests",
#   "rich",
# ]
# ///

import requests
from rich import print

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

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

常用使用范例

范例 1：创建 FastAPI 项目

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
# 初始化项目
uv init fastapi-app
cd fastapi-app

# 添加依赖
uv add fastapi "uvicorn[standard]"
uv add --dev pytest httpx

# 创建应用
cat > main.py << 'EOF'
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello World"}
EOF

# 运行应用
uv run uvicorn main:app --reload

范例 2：数据科学项目

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# 创建项目
uv init data-analysis
cd data-analysis

# 指定 Python 版本
uv python pin 3.11

# 添加数据科学工具
uv add pandas numpy matplotlib jupyter

# 启动 Jupyter
uv run jupyter notebook

范例 3：从 requirements.txt 迁移

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# 假设你有现有的 requirements.txt
# 创建 uv 项目
uv init --no-readme existing-project
cd existing-project

# 从 requirements.txt 导入
uv add $(cat requirements.txt)

# 或者使用 pip 安装（兼容模式）
uv pip install -r requirements.txt

范例 4：多环境管理

1
2
3
4
5
6
# 创建不同的虚拟环境
uv venv .venv-py311 --python 3.11
uv venv .venv-py312 --python 3.12

# 在特定环境中运行
uv run --python 3.11 python script.py

范例 5：CI/CD 配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# .github/workflows/test.yml
name: Test

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install uv
        uses: astral-sh/setup-uv@v3
      
      - name: Set up Python
        run: uv python install
      
      - name: Install dependencies
        run: uv sync --all-extras --dev
      
      - name: Run tests
        run: uv run pytest
      
      - name: Run linting
        run: uv run ruff check .

范例 6：Docker 集成

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
# Dockerfile
FROM python:3.12-slim

# 安装 uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv

# 设置工作目录
WORKDIR /app

# 复制项目文件
COPY pyproject.toml uv.lock ./

# 安装依赖
RUN uv sync --frozen --no-cache

# 复制应用代码
COPY . .

# 运行应用
CMD ["uv", "run", "uvicorn", "main:app", "--host", "0.0.0.0"]

性能对比

以下是 uv 与传统工具的性能对比（基于真实项目测试）：

操作	pip/venv	uv	提升倍数
创建虚拟环境	2.5s	0.1s	25x
安装 Flask + 依赖	8.2s	0.4s	20x
安装 Django + 依赖	15.3s	0.6s	25x
安装 pandas + numpy	12.7s	0.5s	25x
重新安装（缓存）	6.1s	0.05s	122x

与其他工具的对比

uv vs Poetry

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
# Poetry
poetry new myproject
poetry add requests
poetry install
poetry run python script.py
poetry build
poetry publish

# uv（更快、更简单）
uv init myproject
uv add requests
uv sync
uv run python script.py
uv build
uv publish

uv 优势：

速度快 10-50 倍
更简单的命令
内置 Python 版本管理
更小的配置文件

uv vs pipenv

1
2
3
4
5
6
7
8
# Pipenv
pipenv install requests
pipenv shell
python script.py

# uv
uv add requests
uv run python script.py

uv 优势：

解析速度快数十倍
不需要激活环境
更好的依赖解析

配置和最佳实践

pyproject.toml 配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
[project]
name = "my-awesome-project"
version = "0.1.0"
description = "An awesome Python project"
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
    "fastapi>=0.115.0",
    "uvicorn[standard]>=0.32.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=8.0.0",
    "ruff>=0.8.0",
    "black>=24.0.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.uv]
dev-dependencies = [
    "pytest>=8.0.0",
]

最佳实践

始终使用锁文件

1
2
3
4
5
# 生成 uv.lock
uv lock

# 在 CI/CD 中使用
uv sync --frozen

版本约束

1
2
3
4
5
# 精确版本
uv add "fastapi==0.115.0"

# 兼容版本
uv add "fastapi>=0.115.0,<0.116.0"

使用 .python-version

1
2
echo "3.12" > .python-version
uv python install  # 自动安装正确版本

环境变量

1
2
3
4
5
# 自定义缓存位置
export UV_CACHE_DIR=/path/to/cache

# 使用系统 Python
export UV_SYSTEM_PYTHON=1

从现有工具迁移

从 pip/venv 迁移

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# 1. 初始化 uv 项目
uv init --no-readme .

# 2. 添加现有依赖
uv pip install -r requirements.txt

# 3. 生成 pyproject.toml
uv add $(cat requirements.txt)

# 4. 删除旧文件（可选）
rm requirements.txt

从 Poetry 迁移

1
2
3
4
5
6
7
8
# 1. 转换 pyproject.toml（uv 可以读取 Poetry 格式）
# Poetry 的 pyproject.toml 大多数情况下可以直接使用

# 2. 安装依赖
uv sync

# 3. 更新 poetry.lock 为 uv.lock
uv lock

从 Conda 迁移

1
2
3
4
5
6
7
8
# 1. 导出 Conda 环境
conda list --export > conda-requirements.txt

# 2. 创建 uv 项目
uv init project-name

# 3. 手动添加 PyPI 可用的包
uv add package1 package2 package3

macOS 特定提示

作为 macOS 用户，以下是一些额外的技巧：

安装 uv

1
2
3
4
5
# 使用 Homebrew（推荐）
brew install uv

# 或使用官方安装脚本
curl -LsSf https://astral.sh/uv/install.sh | sh

Shell 集成

1
2
3
4
5
# 添加到 ~/.zshrc（macOS 默认 shell）
eval "$(uv generate-shell-completion zsh)"

# 或 ~/.bash_profile
eval "$(uv generate-shell-completion bash)"

与系统 Python 配合

1
2
3
4
5
6
7
8
# macOS 通常自带 Python 3
# uv 可以使用系统 Python 或安装独立版本

# 使用系统 Python
uv venv --python /usr/bin/python3

# 或让 uv 管理 Python 版本
uv python install 3.12

故障排除

常见问题

问题 1：找不到 Python 版本

1
2
# 解决方案：安装所需版本
uv python install 3.11

问题 2：锁文件冲突

1
2
# 解决方案：重新生成锁文件
uv lock --upgrade

问题 3：缓存问题

1
2
3
4
5
# 清除缓存
uv cache clean

# 查看缓存大小
uv cache dir

总结

uv 代表着 Python 工具链近十年来最重要的进步之一。它不仅仅是更快的工具，而是对整个 Python 开发体验的重新思考：

✅ 统一：一个工具替代十几个工具
✅ 快速：10-100x 的性能提升
✅ 简单：直观的命令和工作流
✅ 现代：内置版本管理和锁文件
✅ 可靠：精确的依赖解析和可复现构建

对于任何 Python 开发者，特别是有 10 年经验的 DevOps 工程师来说，uv 是值得立即采用的工具。它简化了我们的工具栈，节省了大量时间，并为 Python 生态系统带来了我们长期以来一直需要的凝聚力。

资源链接

开始使用 uv，体验 Python 开发的未来！

1
2
3
4
5
brew install uv
uv init my-project
cd my-project
uv add fastapi
uv run python -c "print('Hello, uv!')"