UV：下一代 Python 包管理工具完全指南

从 pip 到 uv ：用 Rust 重构 Python 开发体验，让依赖管理快 10 倍

🎯 UV 是由 Astral 团队（知名 Python 代码检查工具 Ruff 的缔造者）基于 Rust 开发的新一代 Python 包与项目管理工具。它通过单一工具链替代传统的 pip、pip-tools、pipx、poetry、pyenv、virtualenv 等零散工具，正在重塑 Python 开发工作流。

🌟 为什么选择 UV？核心特性一览

特性	能力说明	传统工具对比
🚀 All-in-One	单一工具覆盖包管理、虚拟环境、Python 版本、CLI 工具发布	替代 pip+pip-tools+pipx+poetry+pyenv+virtualenv
⚡ 极致性能	依赖解析与安装速度比 pip 快 10-100 倍	告别 pip install 转圈圈
🗂️ 现代项目管理	内置 通用锁文件(uv.lock) 与 Cargo 风格工作区	比 requirements.txt 更可靠的版本锁定
❇️ 脚本即运行	支持 PEP 723 内联依赖元数据，单文件也能自动管理依赖	无需手动创建虚拟环境即可运行独立脚本
🐍 Python 版本管理	内置 pyenv 功能，自动下载、安装、切换 Python 解释器	uv python install 3.12 一键搞定
🛠️ 全局工具隔离	直接运行和安装 Python CLI 工具（如 black、ruff），与项目依赖完全隔离	比 pipx 更轻量的工具管理
🔩 零成本迁移	提供 pip 兼容接口，uv pip install 直接替换 pip install	现有项目无缝切换
💾 磁盘空间优化	通过全局缓存实现依赖去重，多项目共享同一份库文件	节省 60%+ 磁盘空间
⏬ 开箱即用	无需预装 Rust 或 Python，通过 curl 或 pip 一键安装	单二进制文件，跨平台支持

---

一、极速安装指南

🔥 推荐方式：官方安装脚本（跨平台）

macOS / Linux：

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

Windows (PowerShell)：

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

📦 手动下载（离线环境）

访问 GitHub Releases 下载对应平台安装包。如遇下载缓慢，可使用 GitHub 加速代理：

# Windows 示例（v0.10.5）
https://gh-proxy.com/github.com/astral-sh/uv/releases/download/0.10.5/uv-x86_64-pc-windows-msvc.zip
# Linux 示例（x86 v0.10.5）
https://gh-proxy.com/github.com/astral-sh/uv/releases/download/0.10.5/uv-x86_64-unknown-linux-gnu.tar.gz

💡 Windows 用户建议：将 uv.exe 解压至固定目录（如 D:\Tools\uv），避免中文路径或含空格路径，后续需配置环境变量。

---

二、环境变量配置（关键步骤）

UV 通过环境变量实现全局配置。建议国内用户必配镜像源，可大幅提升使用体验。

2.1 推荐配置清单

环境变量	作用说明	推荐配置值（国内加速版）
UV_HOME	UV 安装主目录（需加入系统 PATH）	D:\uv (Win) 或 $HOME/.local/bin (Unix)
UV_CACHE_DIR	依赖缓存存储路径（可跨项目共享）	D:\uv\cache
UV_TOOL_DIR	全局 CLI 工具安装目录	D:\uv\tools
UV_PYTHON_INSTALL_DIR	Python 解释器下载存放位置	D:\uv\python
UV_DEFAULT_INDEX	PyPI 镜像源（依赖下载加速）	https://pypi.tuna.tsinghua.edu.cn/simple
UV_PYTHON_INSTALL_MIRROR	Python 官方镜像（解释器下载加速）	https://gh-proxy.com/github.com/astral-sh/python-build-standalone/releases/download

2.2 配置方式

Windows 用户：

1. Win + R → 输入 sysdm.cpl → 高级 → 环境变量
2. 新建上述变量，将 %UV_HOME% 加入系统 Path
3. 建议目录结构：D:\uv 下创建 cache、tools、python 子目录，便于统一管理

macOS / Linux 用户： 编辑 shell 配置文件（~/.bashrc、~/.zshrc 或 ~/.config/fish/config.fish）：

# UV 配置
export UV_HOME="$HOME/.local/bin"
export UV_CACHE_DIR="$HOME/.cache/uv"
export UV_TOOL_DIR="$HOME/.local/share/uv/tools"
export UV_PYTHON_INSTALL_DIR="$HOME/.local/share/uv/python"
export UV_DEFAULT_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple"
export UV_PYTHON_INSTALL_MIRROR="https://gh-proxy.com/github.com/astral-sh/python-build-standalone/releases/download"

# 确保 UV 在 PATH 中
export PATH="$UV_HOME:$PATH"

配置完成后执行 source ~/.bashrc（或重启终端）生效。

⚠️ 注意：若不配置 UV_DEFAULT_INDEX，首次下载依赖时可能因网络问题超时。建议所有国内用户配置清华或阿里镜像源。

---

三、验证安装与环境

重新打开终端，依次执行以下命令验证配置是否生效：

# 1. 查看 UV 版本（确认 PATH 配置正确）
uv --version
# 预期输出：uv 0.10.5

# 2. 查看 Python 解释器安装目录
uv python dir
# 预期输出：D:\uv\python 或 /home/username/.local/share/uv/python

# 3. 查看全局缓存目录（确认磁盘优化生效）
uv cache dir

# 4. 测试 Python 下载镜像（-v 查看详细日志）
uv python install -v 3.12.12
# 应看到从配置的镜像地址下载，而非 github.com

---

四、核心工作流实战

4.1 Python 版本管理（替代 pyenv）

# 查看所有可安装的 Python 版本（包括预发布版）
uv python list --all-versions

# 安装指定版本（支持模糊匹配，自动选最新补丁版）
uv python install 3.12        # 安装最新 3.12.x
uv python install 3.11 3.12   # 同时安装多个版本

# 设置全局默认 Python（创建符号链接）
uv python default 3.12

# 查看已安装版本
uv python list --only-installed

4.2 包管理：pip 兼容模式（迁移零成本）

适合现有项目的快速迁移，命令与 pip 几乎完全一致：

# 基础安装（自动识别当前虚拟环境或系统环境）
uv pip install requests

# 精确版本控制
uv pip install requests==2.31.0 "numpy>=1.24"

# 从 requirements.txt 安装（速度提升最明显）
uv pip install -r requirements.txt

# 开发依赖管理（写入 pyproject.toml 的 [project.optional-dependencies]）
uv pip install --dev pytest black

# 导出生产环境依赖（排除 dev 依赖）
uv pip freeze --production > requirements.lock

# 卸载与清理
uv pip uninstall requests
uv pip prune  # 清理未使用的依赖

4.3 现代项目管理（推荐新项目的标准流程）

UV 的杀手级功能，提供类似 Poetry 的体验但速度更快：

# 1. 初始化新项目（自动生成 pyproject.toml 和项目结构）
uv init my_project
cd my_project

# 2. 锁定 Python 版本（创建 .python-version 文件，团队成员自动同步）
uv python pin 3.12

# 3. 添加依赖（自动更新 pyproject.toml 和 uv.lock）
uv add fastapi
uv add --dev pytest mypy  # 开发依赖

# 4. 同步环境（根据 lock 文件创建/更新虚拟环境，确保一致性）
uv sync

# 5. 运行项目（无需手动激活虚拟环境，UV 自动识别）
uv run python main.py
uv run fastapi dev        # 运行包提供的 CLI 命令

4.4 旧项目迁移实战（pip → UV）

对于使用 pip + requirements.txt 的遗留项目：

cd legacy_project

# 步骤 1：初始化 UV 配置（检测现有依赖）
uv init

# 步骤 2：创建虚拟环境并指定 Python 版本
uv venv --python 3.12

# 步骤 3：导入现有依赖（保留版本约束，自动生成 uv.lock）
uv add -r requirements.txt

# 步骤 4：验证环境完整性
uv sync

# 步骤 5：后续使用 UV 管理依赖（可选）
rm requirements.txt  # 不再需要，uv.lock 已接管

📝 迁移提示：UV 会读取现有的 requirements.txt，但建议迁移后使用 uv add 管理新依赖，利用 uv.lock 确保团队环境 100% 一致。

---

五、高级用法与最佳实践

5.1 单文件脚本依赖（PEP 723）

无需 pyproject.toml，直接在 Python 脚本中声明依赖：

# main.py
# /// script
# dependencies = ["requests>=2.31", "rich"]
# requires-python = ">=3.11"
# ///

import requests
from rich import print

print("[bold green]Hello UV![/bold green]")
print(requests.get("https://api.github.com").json())

运行方式：

uv run main.py
# UV 会自动创建临时环境，安装依赖，执行脚本，无需手动管理虚拟环境

5.2 全局工具管理（替代 pipx）

安装 CLI 工具到隔离环境，避免污染系统 Python：

# 安装工具（如 black、ruff、httpie）
uv tool install ruff
uv tool install black

# 运行工具（无需安装，临时环境执行）
uv tool run ruff check .
# 或简写
uvx ruff check .

# 查看已安装工具
uv tool list

# 升级工具
uv tool upgrade ruff

5.3 工作区管理（Monorepo 支持）

大型项目多包管理，类似 Rust Cargo Workspace：

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

---

💡 给团队的建议

1. 提交 uv.lock 到版本控制：这是 UV 的核心优势，确保 CI/CD 和团队成员的依赖版本完全一致（比 requirements.txt 更可靠）。

2. 使用 uv run 替代 source venv/bin/activate：在 README 中统一使用 uv run python main.py，消除"虚拟环境未激活"导致的错误。

3. CI/CD 集成：

   # GitHub Actions 示例
   - name: Install UV
     uses: astral-sh/setup-uv@v3
   - name: Sync dependencies
     run: uv sync --frozen  # 严格按 lock 文件安装
   - name: Run tests
     run: uv run pytest

4. 磁盘空间焦虑：UV 的全局缓存会自动去重，多个项目依赖同一个包时只存一份，通常比传统虚拟环境节省 50% 以上空间。

---

📚 延伸阅读与资源

• 📖 UV 官方中文文档（由社区维护，更新及时）
• 🚀 GitHub 加速代理（解决国内下载慢问题）
• 🐙 UV GitHub 仓库（Star 数增长极快，值得关注）
• 🎥 Astral 团队博客（了解 Rust 重构 Python 工具链的技术细节）

---

你在使用 UV 过程中遇到过哪些问题？欢迎在评论区分享你的迁移经验！ 如果觉得有用，欢迎点赞收藏，转发给还在被 pip 慢困扰的 Python 开发者 👋

---

排版建议（针对公众号/知乎编辑器）

1. 代码块样式

• 建议使用 Monokai 或 Dracula 深色主题，关键字高亮（uv 命令用蓝色，路径用橙色）
• 行号建议关闭，移动端阅读更清爽

2. 重点标注

• 关键命令如 uv sync、uv run 可用红色加粗或高亮背景
• 环境变量表格建议截图后插入，避免移动端表格显示错乱

3. 视觉分隔

• 在"核心特性"和"安装指南"之间可插入 UV Logo 或 Astral 团队图标
• 使用 --- 水平线分隔大章节，提升长文阅读节奏感

4. 交互增强（公众号特有）

• 在"验证安装"部分可添加"点击复制"按钮（使用公众号代码块插件）
• 文末可添加投票："你目前使用什么工具管理 Python 依赖？A) pip B) conda C) poetry D) 已切换到 UV"