uv 简介

uv：新一代 Python 包管理工具

什么是 uv

uv 是由 Astral 公司（Rust 工具 Ruff 的开发者）开发的 Python 包管理和项目工具，用 Rust 编写，主打极速和统一。

uv 可以替代以下多种传统工具：

传统工具	uv 对应功能
pip	uv add
pipx	uv tool
pyenv	uv python

安装 uv

方式一：官方安装脚本（推荐）

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

方式二：pip 安装

pip install uv

切换国内镜像源

修改全局配置文件 ~/.config/uv/uv.toml（Linux/macOS）

[[index]]
url = "https://mirrors.ustc.edu.cn/pypi/simple"
default = true

让其在终端中，能自动补全，根据不同终端，增添如下配置

# Bash
echo 'eval "$(uvx --generate-shell-completion bash)"' >> ~/.bashrc
# Zsh
echo 'eval "$(uvx --generate-shell-completion zsh)"' >> ~/.zshrc

安装完成后，验证版本：

uv --version
# uv 0.5.x

推荐使用官方安装脚本，因为可通过 uv self update 直接升级；pip 安装的 uv 需要通过 pip 来升级，依赖管理较麻烦。

1. 创建虚拟环境

# 创建虚拟环境（默认在 .venv）
uv venv

# 指定 Python 版本创建虚拟环境
uv venv --python 3.12

# 使用系统已安装的 Python
uv venv --python python3.11

2. 安装依赖

# 安装单个包（面向项目，会写入 pyproject.toml）
uv add requests

# 安装多个包
uv add flask django

# 从 requirements.txt 安装
uv pip install -r requirements.txt

# 安装特定版本
uv add "requests>=2.28"

3. 管理项目依赖

uv 支持两种依赖声明文件：requirements.txt 和 pyproject.toml。

# 编译依赖（类似 pip-compile）
uv pip compile requirements.in -o requirements.txt

# 同步依赖到虚拟环境
uv pip sync requirements.txt

4. 管理 Python 版本

# 列出可安装的 Python 版本
uv python list

# 安装指定版本
uv python install 3.12

# 卸载 Python 版本
uv python uninstall 3.11

5. 使用工具（替代 pipx）

# 安装全局工具
uv tool install httpie

# 运行工具（无需长期安装）
uvx httpie GET https://httpbin.org/get

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

# 升级工具
uv tool upgrade httpie

# 卸载工具
uv tool uninstall httpie

6. 快速运行 Python 脚本

uv run script.py

uv 会自动创建临时环境、安装依赖、执行脚本、清理环境，一气呵成。

7. 卸载包

uv remove requests

常用配置

uv 默认配置存储在 ~/.config/uv/ 目录（Linux/Mac）或 %APPDATA%\uv\（Windows）。

常用环境变量：

环境变量	说明
UV_PYTHON	指定默认 Python 版本
UV_CACHE_DIR	缓存目录
UV_NO_PROGRESS	禁用进度条

性能对比

uv 的核心优势是速度。以下是官方基准测试的典型场景对比：

操作	pip	uv	提升
安装 100 个包	~60s	~3s	~20x
冷创建虚拟环境	~3s	~0.3s	~10x

进阶功能

工作流命令

# 初始化新项目
uv init myproject

# 进入项目目录并创建虚拟环境
cd myproject
uv venv

# 添加依赖（会写入 pyproject.toml）
uv add requests flask

# 移除依赖
uv remove django

# 锁定依赖
uv lock

# 运行脚本（自动管理环境）
uv run main.py

与 pip 工作流对比

pip 工作流	uv 对应	说明
pip-compile requirements.in -o requirements.txt	uv lock	生成锁文件（uv.lock），极速版
pip install -r requirements.txt	uv sync	根据锁文件安装依赖

常见问题

Q: uv add 和 uv pip install 有什么区别？
A: uv add 是面向项目的命令，会自动将依赖写入 pyproject.toml；uv pip install 更接近 pip 的直接操作方式，不修改项目文件。

Q: uv 与 pip 完全兼容吗？
A: 基本兼容，uv 支持 pip 的大多数参数。但部分高级功能（如 --no-deps 的特殊行为）可能存在差异。

Q: 可以同时使用 pip 和 uv 吗？
A: 可以，但建议避免混用。uv 的 uv pip sync 可以锁定环境与 requirements.txt 完全一致。

Q: uv 支持私有仓库吗？
A: 支持，通过 UV_INDEX_URL 环境变量或 pip.conf 配置认证的私有 PyPI 镜像。

总结

uv 是一个「合一」的 Python 工具链，适合想要简化工具链、提升开发效率的开发者。其 Rust 实现带来的速度优势在实际使用中非常明显，值得尝试。

---

参考资料：uv 官方文档