uv 完整指南：现代 Python 软件包管理
uv 是一个极速的 Python 软件包和项目管理器，由 Rust 编写。它提供了一个统一的界面来管理 Python 依赖项、虚拟环境、Python 版本和项目。
什么是 uv？
核心架构
| 组件 | 语言 | 用途 | 替代工具 |
|---|---|---|---|
| 软件包安装程序 | Rust | 快速依赖项解析和安装 | pip |
| 项目管理器 | Rust | 带有锁定文件的现代项目管理 | poetry, pip-tools |
| 环境管理器 | Rust | 虚拟环境创建和管理 | virtualenv, venv |
| Python 版本管理器 | Rust | 安装和切换 Python 版本 | pyenv |
| 工具运行程序 | Rust | 从软件包中执行 CLI 工具 | pipx |
| 软件包发布者 | Rust | 构建和发布分发版 | twine |
核心特性
- 🚀 统一工具链：单个命令即可替代 8 个以上的 Python 工具。
- ⚡️ 极致性能：比 pip 快 10-100 倍（基准测试）。
- 🗂️ 项目管理：跨平台通用锁定文件支持。
- 🐍 Python 管理：安装和管理多个 Python 版本。
- 💾 全局缓存：磁盘空间高效的依赖项去重。
为什么使用 uv？
性能基准测试
| 操作 | pip 时间 | uv 时间 | 速度提升 |
|---|---|---|---|
安装 requests（冷缓存） | 1.2s | 0.08s | 15 倍更快 |
安装 Flask（热缓存） | 0.8s | 0.01s | 80 倍更快 |
| 解析 50 个软件包 | 2.5s | 0.03s | 83 倍更快 |
| 创建虚拟环境 | 0.5s | 0.02s | 25 倍更快 |
工作流对比
传统工作流（需要 6+ 工具）
# 安装 Python, 创建 venv, 安装依赖, 锁定, 构建...
pyenv install 3.11.0
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip-compile requirements.in -o requirements.txt
python -m build
现代 uv 工作流（1 个工具）
# 一个工具搞定所有事
uv init myproject --python 3.11.0
uv add requests flask
uv lock
uv build
快速上手
安装方式
| 平台 | 命令 |
|---|---|
| macOS / Linux | `curl -LsSf https://astral.sh/uv/install.sh |
| Windows | `powershell -c "irm https://astral.sh/uv/install.ps1 |
| Homebrew | brew install uv |
pip 命令替换表
| pip 命令 | uv 等效命令 |
|---|---|
pip install package | uv pip install package |
pip install -r reqs.txt | uv pip install -r reqs.txt |
python -m venv .venv | uv venv |
pip list | uv pip list |
pip freeze | uv pip freeze |
现代项目管理
项目初始化
使用 uv init 快速创建具有标准化结构的新 Python 项目：
# 基础用法：在当前目录初始化
uv init
# 创建新的项目目录
uv init myproject
# 指定 Python 版本
uv init --python 3.11
# 创建应用程序（非库）
uv init --app myapp
# 包含 README 文件
uv init --readme myproject
# 创建不带虚拟环境的项目
uv init --no-venv myproject
生成的项目结构：
myproject/
├── pyproject.toml # 项目元数据和依赖项
├── uv.lock # 通用锁定文件 (提交至 Git)
├── .python-version # Python 版本规范
├── README.md # 项目说明（可选）
└── src/
└── myproject/
└── __init__.py # 包初始化
uv init 生成的 pyproject.toml 文件遵循 PEP 621 标准。如需了解各字段的详细说明和配置最佳实践，请参阅 pyproject.toml 完整指南。
项目结构
myproject/
├── pyproject.toml # 项目元数据和依赖项
├── uv.lock # 通用锁定文件 (提交至 Git)
├── .python-version # Python 版本规范
├── src/ # 源代码
└── tests/ # 测试文件
依赖项管理
- 添加依赖项：
uv add requests - 添加开发依賴項：
uv add --dev pytest - 同步环境：
uv sync（确保.venv与uv.lock一致） - 运行命令：
uv run python main.py（自动处理 venv）
最佳实践
始终将 uv.lock 提交到你的存储库。它能确保每个团队成员和 CI 环境使用完全相同的依赖项版本。
进阶功能
脚本支持
运行带有内联依赖项元数据的独立脚本：
# /// script
# dependencies = ["requests", "rich"]
# ///
import requests
from rich import print
print(requests.get("https://api.github.com").status_code)
运行命令：uv run script.py
工具管理
全局安装和运行 Python CLI 工具，而不会污染系统 Python：
uv tool install ruff
uvx ruff check . # 无需永久安装即可运行
Python 管理
uv python install 3.11 3.12 # 安装特定版本
uv python list # 列出已安装版本
CI/CD 集成
GitHub Actions
- uses: astral-sh/setup-uv@v3
- run: uv sync
- run: uv run pytest
Docker
FROM python:3.11-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev
与第三方包管理器集成
某些生态系统（如 OpenMMLab）使用自己的包管理器。uv 负责虚拟环境，这些工具管理各自的包。
工作流程
# 1. 用 uv 创建 venv
uv venv .venv
source .venv/bin/activate
# 2. 通过 uv 安装第三方包管理器
uv pip install openmim
# 3. 用该管理器安装生态内的包
mim install mmdet mmdet3d mmyolo
核心原则
uv 管理环境和 pip 操作；第三方管理器处理其自有的包版本。只要在运行管理器前激活 venv，包就会安装到正确位置。
避免环境混淆
如果未激活 venv，mim install 可能不会使用正确的 pip。使用以下模式之一：
# 链式激活和安装
source .venv/bin/activate && mim install mmdet
# 或通过 venv 的 Python 直接调用 mim
.venv/bin/python -m mim install mmdet
# 或使用 uv run
uv pip install openmim && uv run mim install mmdet
使用 uv run 时，环境会自动正确配置：
uv run mim install mmdet # uv 自动处理环境
总结与建议
- 采用
uv init：为新项目使用项目管理功能。 - 使用
uv run：停止手动激活虚拟环境。 - 提交
uv.lock：确保所有环境的可复现性。 - 使用
uv tool：替代pipx管理全局 CLI 工具。