uv 工具详解——Python 包与项目管理器完全指南

标签：Python · uv · 包管理 · 环境管理 · Rust · 工具链
摘要：uv 是由 Astral（Ruff 缔造者）用 Rust 编写的极速 Python 包和项目管理工具，一个命令替代 pip、pipx、pyenv、poetry、venv、twine、pip-tools。本文从安装到核心用法，结合图文完整介绍这一现代化 Python 开发利器。

---

目录

1. 什么是 uv？
2. 性能优势：比 pip 快 10～100 倍
3. 安装方法（多平台）
4. uv 能替代哪些工具？
5. Python 版本管理
6. 项目管理：init / add / sync / run
7. 依赖管理详解
8. uvx：即开即用的 CLI 工具
9. pip 兼容接口
10. 升级、卸载与 Shell 补全
11. 总结

---

一、什么是 uv？

uv 是由 Astral（知名 Python 代码检查工具 Ruff 的开发团队）推出的 Python 包和项目管理器，完全使用 Rust 编写。

图1：uv —— 一个工具替代整个 Python 工具链

核心理念：用一个统一、极速的工具替代 Python 生态中碎片化的多个工具，让包安装、项目初始化、依赖锁定、版本管理、CLI 工具运行等操作全部一站搞定。

uv 的四大设计原则：

原则	说明
🚀 极速	Rust 编写，全局缓存，并行安装，比 pip 快 10～100 倍
🛠️ 全能	一站式替代多个工具，无需组合使用
🔒 可复现	通用锁文件 uv.lock，确保跨平台、跨机器环境一致
📦 零门槛	独立安装程序，无需预装 Rust 或 Python，一行命令搞定

---

二、性能优势：比 pip 快 10～100 倍

uv 最大的亮点之一是极致的安装速度，这是因为：

• Rust 实现：编译型语言，天生高性能，内存安全
• 全局缓存：相同依赖只下载一次，磁盘空间高效利用
• 并行解析：依赖解析在毫秒级完成

图2：uv vs pip 在不同规模安装任务下的耗时对比（紫色=uv，灰色=pip）

操作	uv 耗时	pip 耗时	提速倍数
安装 Flask（1个包）	0.3s	~11s	约 37 倍
安装 requests（含依赖）	0.4s	~14s	约 35 倍
安装 10 个包（含全部依赖）	1.2s	~60s	约 50 倍
安装 Django 等（约25个包）	3.5s	~110s	约 31 倍
安装完整科学计算栈（50+包）	8s	~180s	约 22 倍

数据来源：Astral 官方基准测试。实际提速因网络、环境而异，但即使是最简单场景也有 10 倍以上的提升。

---

三、安装方法（多平台）

uv 支持多种安装方式，无论你使用什么操作系统，总有一种适合你。

图3：uv 多平台安装方式——curl、PowerShell、pipx、Homebrew、Winget 均可

3.1 macOS / Linux（推荐）

# 标准安装（推荐）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 如果没有 curl，用 wget
wget -qO- https://astral.sh/uv/install.sh | sh

# Homebrew
brew install uv

3.2 Windows（推荐）

# PowerShell（推荐）
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Winget
winget install --id=astral-sh.uv -e

# Scoop
scoop install main/uv

3.3 pip / pipx 安装

# 推荐：pipx 隔离安装（推荐）
pipx install uv

# 或直接用 pip
pip install uv

3.4 其他方式

方式	命令
Docker	docker run ghcr.io/astral-sh/uv
GitHub Releases	直接下载对应平台的二进制文件
Cargo（从源码）	cargo install --git https://github.com/astral-sh/uv uv

💡 安装前无需安装 Rust 或 Python，uv 的独立安装包自带 Rust 运行时，Windows 用户只需 PowerShell 即可。

---

四、uv 能替代哪些工具？

这是 uv 最令人印象深刻的地方——一个工具替代七个常用工具：

被替代的工具	uv 对应命令	功能
pip	uv pip install	包安装（兼容 pip 接口）
pipx	uvx / uv tool run	CLI 工具临时运行
pyenv	uv python install	Python 版本管理
poetry	uv init / uv add / uv sync	项目依赖管理
venv / virtualenv	uv venv	虚拟环境创建
pip-tools	uv lock / uv pip compile	依赖锁定
twine	uv build / uv publish	包构建与发布
rye	uv（本身）	综合管理

---

五、Python 版本管理

uv 内置了完整的 Python 版本管理器，无需再安装 pyenv。

图5：uv python list 查看可用版本 / uv python pin 固定项目版本

常用命令

# 安装多个 Python 版本
uv python install 3.10 3.11 3.12 3.13

# 查看所有可用版本（包括已安装的）
uv python list

# 查找已安装的 Python 路径
uv python find

# 固定当前项目使用特定 Python 版本（写入 .python-version）
uv python pin 3.11

# 卸载指定版本
uv python uninstall 3.10

# 更新补丁版本（如 3.12.3 -> 3.12.4）
uv python update

# 查看 Python 安装目录
uv python dir

uv python list 输出说明：

• cp312 / cp311：CPython 3.12 / 3.11
• managed：uv 管理的版本
• requires-uv：需要 uv 才能使用的版本
• downloadable：可下载但未安装

.python-version 文件

uv python pin 3.12 会在项目根目录生成 .python-version 文件，内容只有一行：

3.12

该文件提交到 Git 后，团队成员克隆项目后运行 uv sync，uv 会自动下载并切换到指定版本，保证团队环境完全一致。

---

六、项目管理：init / add / sync / run

这是 uv 最核心的日常开发工作流，四个命令覆盖项目全生命周期。

图4：uv 项目开发标准工作流——init 创建 → add 添加依赖 → sync 同步环境 → run 运行

6.1 uv init —— 创建新项目

# 创建并进入新项目目录
uv init hello-world
cd hello-world

# 或在已有目录初始化
mkdir hello-world && cd hello-world
uv init

uv init 会在目录中生成以下文件：

文件	说明
pyproject.toml	项目配置 + 依赖声明（核心文件）
.python-version	项目固定 Python 版本
main.py	入口文件（含 Hello World 示例）
README.md	项目说明文档

6.2 uv add —— 添加依赖

# 添加生产依赖
uv add requests flask

# 添加开发依赖（仅在开发时需要）
uv add --dev pytest black

# 添加可选依赖组
uv add --optional notebook jupyter

执行 uv add 后，pyproject.toml 会自动更新：

[project]
name = "hello-world"
version = "0.1.0"
dependencies = ["requests", "flask"]

自动写入，无需手动编辑——这是 uv 比原生 pip 最大的体验提升。

6.3 uv sync —— 同步环境

# 同步依赖到本地 .venv
uv sync

uv sync 会根据 pyproject.toml 和 uv.lock 将依赖安装到 .venv 虚拟环境中。

# 激活虚拟环境（可选，uv run 不需要）
source .venv/bin/activate  # macOS / Linux
.venv\Scripts\activate     # Windows

# 然后运行项目
python main.py

6.4 uv run —— 运行（最推荐的方式）

# 直接运行脚本，自动完成：校验锁文件 → 同步环境 → 执行命令
uv run python main.py

# 运行 Flask 应用
uv run -- flask run -p 3000

# 运行 pytest 测试
uv run pytest tests/

uv run 是最推荐的运行方式——它自动确保 uv.lock 和 pyproject.toml 的一致性，无需手动激活虚拟环境，三步操作合一。

6.5 uv lock —— 锁定依赖

# 更新锁文件（根据 pyproject.toml 生成/更新 uv.lock）
uv lock

# 升级指定包到最新兼容版本
uv lock --upgrade-package requests

uv.lock 是 uv 的锁文件，记录每个依赖包的确切版本和来源，确保团队成员和 CI/CD 环境中依赖完全一致。

---

七、依赖管理详解

7.1 项目级依赖

# 添加依赖
uv add httpx pandas

# 移除依赖
uv remove httpx

# 查看依赖树
uv tree

7.2 脚本级依赖（单文件脚本）

uv 支持内联依赖的 Python 脚本，不需要 pyproject.toml，直接在脚本顶部声明：

# /// script
# requires-python = ">=3.11"
# dependencies = [
#   "requests",
#   "flask>=2.0",
# ]
# ///

import requests
import flask

# 运行脚本，自动安装声明的依赖
uv run my_script.py

7.3 工作区（Workspace）支持

uv 支持 Cargo 风格的工作区，适合大型多包项目：

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

---

八、uvx：即开即用的 CLI 工具

uvx（等价于 uv tool run）让你无需全局安装，直接运行任意 Python CLI 工具。

图6：uvx 工作原理——每次运行自动创建临时隔离环境，工具即开即用，用完自动销毁

使用示例

# 代码检查
uvx ruff check .

# 代码格式化
uvx black src/

# HTTP 客户端
uvx httpy https://httpbin.org/get

# 趣味工具
uvx cowsay "Hello from uvx!"

# Jupyter Notebook
uvx jupyter notebook

工作原理

输入命令 uvx ruff check .
    ↓
下载工具包（首次运行）
    ↓
创建临时 .venv 隔离环境
    ↓
安装依赖 + 运行脚本
    ↓
环境自动销毁（不污染系统）
    ↓
完成 ✓

永久安装工具

如果某个工具需要长期使用，可以永久安装到全局：

# 永久安装
uv tool install cowsay

# 使用（安装后直接运行）
cowsay "Hello!"

# 卸载
uv tool uninstall cowsay

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

---

九、pip 兼容接口

对于遗留项目或需要精细控制的场景，uv 提供了与 pip 完全兼容的接口：

# 安装包（等价于 pip install）
uv pip install requests flask

# 卸载包
uv pip uninstall requests

# 列出已安装的包
uv pip list

# 导出依赖清单
uv pip freeze > requirements.txt

# 查看包信息
uv pip show requests

# 检查环境兼容性
uv pip check

# 依赖树
uv pip tree

# pip-compile：生成锁定文件（等价于 pip-tools）
uv pip compile requirements.in -o requirements.txt

# pip-sync：根据锁定文件同步环境
uv pip sync requirements.txt

⚠️ 注意：uv pip 系列命令与原生 pip 在边缘行为上有细微差异，复杂场景建议参考 pip 兼容性指南。

---

十、升级、卸载与 Shell 补全

10.1 升级 uv

# 通过独立安装程序安装的（推荐）
uv self update

# 通过 pip 安装的
pip install --upgrade uv

10.2 卸载 uv

第一步（可选）：清理缓存和数据

uv cache clean
rm -r "$(uv python dir)"
rm -r "$(uv tool dir)"

第二步：删除二进制文件

# macOS / Linux
rm ~/.local/bin/uv ~/.local/bin/uvx

# Windows
rm $HOME\.local\bin\uv.exe
rm $HOME\.local\bin\uvx.exe

📌 从旧版（0.5.0 之前）升级时：~/.cargo/bin 目录下的旧文件不会自动清理，需手动删除。

10.3 Shell 自动补全

# Bash
echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc

# Zsh
echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc

# Fish
echo 'uv generate-shell-completion fish | source' > ~/.config/fish/completions/uv.fish

# Elvish
echo 'eval (uv generate-shell-completion elvish | slurp)' >> ~/.elvish/rc.elv

配置完成后重启 shell 或重新加载配置文件生效。

---

十一、总结

核心命令速查表

场景	推荐命令
安装 uv	curl -LsSf https://astral.sh/uv/install.sh | sh
创建项目	uv init
添加依赖	uv add <包名>
运行脚本	uv run python main.py
安装 Python	uv python install 3.12
固定版本	uv python pin 3.12
同步环境	uv sync
锁定依赖	uv lock
升级 uv	uv self update
运行 CLI 工具	uvx ruff check .

uv vs 其他工具对比

	uv	pip	Poetry	pipx	pyenv
速度	⚡ 极快	🐢 慢	🐢 慢	⚡ 快	⚡ 快
工具整合	✅ 全能	❌ 单一	⚠️ 部分	❌ 单一	❌ 单一
锁文件	✅ uv.lock	❌	✅ poetry.lock	❌	❌
Python 管理	✅	❌	❌	❌	✅
CLI 工具运行	✅ uvx	❌	❌	✅	❌

一句话推荐

uv = pip + pipx + pyenv + poetry + venv + twine + pip-tools，一个工具，替代整个 Python 工具链。

如果你厌倦了 Python 工具链的碎片化，以及无尽的 pip install 等待，现在就是迁移到 uv 的最佳时机——零门槛，性能提升肉眼可见。

---

参考文档

• uv 官方文档
• Astral 官网
• uv GitHub 仓库
• The Ruff Formatter