uv - 极速 Python 包管理器

概述

uv 是由 Astral 团队开发的极速 Python 包和项目管理器，使用 Rust 语言编写。它是替代 pip、pip-tools、pipx、poetry、pyenv、twine、virtualenv 等工具的一体化解决方案。

核心优势：

比 pip 快 10-100 倍
单一工具替代多个传统工具
提供完整的项目管理功能，支持通用锁文件
管理脚本依赖和独立环境
安装和管理 Python 版本
pip 兼容的命令接口
支持 Cargo 风格的工作空间
高效的全局缓存，减少磁盘占用
无需 Rust 或 Python 环境即可安装
支持 macOS、Linux 和 Windows

开发团队： Astral，同时也是 Ruff（极速 Python linter）和 ty 的创建者。

安装

使用独立安装器

macOS 和 Linux：

bash 复制代码

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows：

powershell 复制代码

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

使用 PyPI 安装

bash 复制代码

# 使用 pip
pip install uv

# 或使用 pipx
pipx install uv

自更新

如果通过独立安装器安装，uv 可以自动更新：

bash 复制代码

uv self update

核心功能

1. 项目管理 (Projects)

uv 提供类似 rye 或 poetry 的项目管理功能，支持锁文件、工作空间等：

console 复制代码

# 创建新项目
$ uv init example
Initialized project `example` at `/home/user/example`

$ cd example

# 添加依赖
$ uv add ruff
Creating virtual environment at: .venv
Resolved 2 packages in 170ms
   Built example @ file:///home/user/example
Prepared 2 packages in 627ms
Installed 2 packages in 1ms
 + example==0.1.0
 + ruff==0.5.0

# 运行命令
$ uv run ruff check
All checks passed!

# 生成锁文件
$ uv lock
Resolved 2 packages in 0.33ms

# 同步依赖
$ uv sync
Resolved 2 packages in 0.70ms
Checked 1 package in 0.02ms

核心命令：

uv init - 初始化新项目
uv add - 添加依赖
uv remove - 移除依赖
uv lock - 生成/更新锁文件
uv sync - 同步环境与锁文件
uv run - 在项目环境中运行命令

2. 脚本管理 (Scripts)

uv 可以管理单文件的脚本依赖，支持内联依赖声明：

console 复制代码

# 创建脚本并添加依赖声明
$ echo 'import requests; print(requests.get("https://astral.sh"))' > example.py

$ uv add --script example.py requests
Updated `example.py`

# 在隔离环境中运行脚本
$ uv run example.py
Reading inline script metadata from: example.py
Installed 5 packages in 12ms
<Response [200]>

脚本内联依赖格式（PEP 723）：

python 复制代码

# /// script
# requires-python = ">=3.11"
# dependencies = [
#     "requests",
#     "rich",
# ]
# ///
import requests
from rich import print

print(requests.get("https://astral.sh"))

3. 工具执行 (Tools)

类似 pipx，uv 可以执行和安装 Python 包提供的命令行工具：

console 复制代码

# 临时运行工具（uvx 是 uv tool run 的别名）
$ uvx pycowsay 'hello world!'
Resolved 1 package in 167ms
Installed 1 package in 9ms
 + pycowsay==0.0.0.2
  """
  ------------
< hello world! >
  ------------
   \   ^__^
    \  (oo)\_______
       (__)\       )\/\
           ||----w |
           ||     ||

console 复制代码

# 安装工具
$ uv tool install ruff
Resolved 1 package in 6ms
Installed 1 package in 2ms
 + ruff==0.5.0
Installed 1 executable: ruff

$ ruff --version
ruff 0.5.0

工具命令：

uv tool run / uvx - 在临时环境中运行工具
uv tool install - 安装工具到用户环境
uv tool uninstall - 卸载工具
uv tool list - 列出已安装的工具
uv tool update-shell - 更新 shell 补全

4. Python 版本管理

uv 可以安装和管理多个 Python 版本：

console 复制代码

# 安装多个版本
$ uv python install 3.12 3.13 3.14
Installed 3 versions in 972ms
 + cpython-3.12.12-macos-aarch64-none (python3.12)
 + cpython-3.13.9-macos-aarch64-none (python3.13)
 + cpython-3.14.0-macos-aarch64-none (python3.14)

# 按需下载特定版本
$ uv venv --python 3.12.0
Using Python 3.12.0
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate

# 使用 PyPy
$ uv run --python pypy@3.8 -- python --version
Python 3.8.16 (a9dbdca6fc3286b0addd2240f11d97d8e8de187a, Dec 29 2022, 11:45:30)
[PyPy 7.3.11 with GCC Apple LLVM 13.1.6 (clang-1316.0.21.2.5)] on darwin

# 固定项目 Python 版本
$ uv python pin 3.11
Pinned `.python-version` to `3.11`

Python 命令：

uv python install - 安装 Python 版本
uv python list - 列出可用/已安装版本
uv python find - 查找 Python 解释器
uv python pin - 固定项目 Python 版本

5. pip 接口 (The pip Interface)

uv 提供 pip、pip-tools、virtualenv 的兼容接口，可以直接替换现有工作流：

console 复制代码

# 编译依赖（类似 pip-compile）
$ uv pip compile requirements.in \
   --universal \
   --output-file requirements.txt
Resolved 43 packages in 12ms

# 创建虚拟环境
$ uv venv
Using Python 3.12.3
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate

# 同步依赖（类似 pip-sync）
$ uv pip sync requirements.txt
Resolved 43 packages in 11ms
Installed 43 packages in 208ms
 + babel==2.15.0
 + black==24.4.2
 + certifi==2024.7.4

pip 兼容命令：

uv pip install - 安装包
uv pip uninstall - 卸载包
uv pip compile - 编译 requirements.in
uv pip sync - 同步 requirements.txt
uv pip freeze - 输出已安装包列表
uv pip list - 列出已安装包
uv pip show - 显示包信息

性能基准测试

基于 Trio 的 docs-requirements.in 进行测试，使用 Python 3.12.4：

热安装（Warm Installation）

已有缓存的情况下重新安装依赖（相当于删除并重建虚拟环境）：

工具	时间
uv	~1ms
pip	~208ms
poetry	~数秒
pdm	~数秒

uv 在热安装场景下比 pip 快 约 200 倍。

冷安装（Cold Installation）

无缓存情况下安装（相当于新机器或 CI 环境）：

uv 在冷安装场景下同样表现优异，比传统工具快 10-100 倍。

热解析（Warm Resolution）

已有缓存但无锁文件时的依赖解析：

uv 的依赖解析速度极快，毫秒级完成复杂依赖树的解析。

冷解析（Cold Resolution）

无缓存时的依赖解析：

即使在无缓存情况下，uv 的解析速度仍远超其他工具。

性能优势来源：

Rust 实现 - 高性能语言编写
并行下载 - 多线程并发获取包
高效缓存 - 全局缓存减少重复下载
Reflinking - macOS 上使用文件引用技术
Hardlinking - Linux 上使用硬链接
PubGrub 算法 - 先进的依赖解析算法

架构设计

依赖解析

uv 使用 PubGrub 算法进行依赖解析，这是先进的版本解决算法，确保：

快速准确的版本计算
清晰的冲突解释
最优化的依赖选择

Git 实现

uv 的 Git 功能基于 Cargo 的实现，支持：

Git 依赖的直接安装
子模块处理
引用和标签解析

缓存机制

uv 使用全局缓存（Global Cache）：

依赖去重 - 不同项目共享下载的包
磁盘高效 - 避免重复存储相同内容
跨项目共享 - 减少网络请求

优化灵感

uv 的部分优化借鉴了：

pnpm - 内容寻址存储
Orogene - 并行处理
Bun - 高效安装策略
Posy - Windows trampoline 技术

高级功能

工作空间 (Workspaces)

支持 Cargo 风格的多包项目管理：

toml 复制代码

# pyproject.toml
[tool.uv.workspace]
members = ["packages/*"]

依赖覆盖

支持版本覆盖、平台独立解析、可复现解析等高级特性。

构建和发布

即使项目不使用 uv 管理，也可以使用 uv 构建和发布：

console 复制代码

$ uv build
$ uv publish

环境变量

uv 支持多种环境变量配置：

UV_PYTHON - 指定 Python 版本
UV_CACHE_DIR - 设置缓存目录
UV_NO_PROGRESS - 禁用进度显示
NO_COLOR - 禁用颜色输出

项目结构

典型的 uv 项目结构：

复制代码

project/
├── .python-version    # 固定的 Python 版本
├── .venv/             # 虚拟环境
├── pyproject.toml     # 项目配置和依赖
├── uv.lock            # 锁文件（通用格式）
└── src/
    └── project/
        └── __init__.py

pyproject.toml 示例

toml 复制代码

[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.28.0",
    "rich>=13.0.0",
]

[tool.uv]
dev-dependencies = [
    "pytest>=7.0.0",
    "ruff>=0.5.0",
]

常见问题 (FAQ)

如何发音？

uv 读作 "you - vee"（/juː viː/）

如何书写？

直接写 "uv"，不要：

使用反引号（除非指代可执行文件）
大写为 "Uv"
全大写为 "UV"（除非是环境变量如 UV_PYTHON）

支持哪些平台？

支持 macOS、Linux 和 Windows。详见平台支持文档。

是否可用于生产环境？

是的，uv 已稳定并广泛应用于生产环境。遵循语义化版本规范。

uv - 极速 Python 包管理器

概述

安装

使用独立安装器

使用 PyPI 安装

自更新

核心功能

1. 项目管理 (Projects)

2. 脚本管理 (Scripts)

3. 工具执行 (Tools)

4. Python 版本管理

5. pip 接口 (The pip Interface)

性能基准测试

热安装（Warm Installation）

冷安装（Cold Installation）

热解析（Warm Resolution）

冷解析（Cold Resolution）

架构设计

依赖解析

Git 实现

缓存机制

优化灵感

高级功能

工作空间 (Workspaces)

依赖覆盖

构建和发布

环境变量

项目结构

pyproject.toml 示例

常见问题 (FAQ)

如何发音？

如何书写？

支持哪些平台？

是否可用于生产环境？

相关资源