Python 包管理新王：uv 全面入门指南

Python 包管理新王：uv 全面入门指南

摘要： uv 是由 Astral 团队（Ruff 的开发者）使用 Rust 编写的 Python 包与项目管理工具，号称比 pip 快 10-100 倍。一个工具就能取代 pip、pip-tools、pipx、poetry、pyenv、virtualenv 等一众老牌工具。本文将从 uv 是什么、为什么值得用、日常如何使用，以及需要注意的事项，带你快速上手这个 Python 生态的新一代基础设施。

来源： uv 官方文档

一、uv 是什么？

uv 是一个用 Rust 编写的极速 Python 包和项目管理工具，由 Astral 团队开发维护。你可能没听过 Astral 这个名字，但你大概率用过（或听说过）他们的另一款明星产品 —— Ruff（Python 领域的极速 Linter 和 Formatter）。

一句话定位

uv 的目标：用一个工具取代 pip、pip-tools、pipx、poetry、pyenv、virtualenv、twine 等一整套 Python 工具链。

在 uv 出现之前，Python 开发者通常需要组合使用多个工具：

  • pip —— 安装包
  • virtualenv / venv —— 虚拟环境
  • pip-tools —— 依赖锁定
  • pipx —— 运行 CLI 工具
  • pyenv —— 管理 Python 版本
  • poetry / rye —— 项目管理

uv 把上面这些能力全部整合到一个命令里，而且速度碾压传统工具。

安装方式

# macOS / Linux（推荐）
curl -LsSf https://astral.sh/uv/install.sh | sh

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

# 也可以通过 pip 安装
pip install uv

安装完成后，uv 命令就可以直接使用了，无需安装 Rust 或 Python 前置环境。

二、uv 的优势 —— 为什么值得用？

1. 速度碾压 —— 比 pip 快 10-100 倍

这是 uv 最核心的卖点。得益于 Rust 的零成本抽象和高效并发处理，uv 在依赖解析、下载、安装等环节都实现了数量级的性能提升。官方基准测试显示：

  • 冷缓存下比 pip 快 10-15 倍
  • 热缓存下比 pip 快 100 倍以上
  • 大型项目的依赖解析从几分钟缩短到几秒

2. 全能 —— 一个工具搞定所有

uv 不是"更快的 pip"，它是一个完整的 Python 项目管理工作流工具：

传统工具链 uv 对应能力
pip uv pip install
pip-tools uv pip compile
pipx uv tool run（uvx）
pyenv uv python install / pin
virtualenv uv venv
poetry / rye uv init / add / sync / run
twine uv build / publish

3. 统一锁文件 —— 可复现的环境

uv 引入了类似 Rust Cargo 风格的 uv.lock 锁文件，这是一个跨平台的统一锁文件，记录了所有依赖的精确版本、哈希值和平台信息。

  • 不同机器、不同 OS 上执行 uv sync 都能得到完全一致的环境
  • 锁文件是人类可读的 TOML 格式（但由 uv 自动管理，不建议手动编辑）
  • 应提交到版本控制中，保证团队协作一致性

4. 全局缓存 + 智能去重 —— 磁盘友好

uv 维护一个全局依赖缓存，所有项目共享同一个缓存目录。同一个包的不同版本在缓存中以内容哈希去重，不会重复下载。

这意味着：

  • 多个项目使用相同的包，磁盘上只存一份
  • 新项目创建时，已缓存的包直接硬链接到虚拟环境，秒级完成
  • 支持 uv cache clean 和 uv cache prune 管理缓存空间

5. 内置 Python 版本管理

不再需要 pyenv 了：

# 安装指定 Python 版本
uv python install 3.12

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

# 为项目指定 Python 版本
uv python pin 3.11

# 按需下载（创建虚拟环境时自动拉取）
uv venv --python 3.12

6. 单文件脚本的依赖管理

uv 支持在 Python 脚本中写内联元数据声明依赖，然后直接 uv run 运行：

# /// script
# requires-python = ">=3.12"
# dependencies = ["requests"]
# ///

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

uv run script.py  # 自动创建临时环境并运行

三、实战操作 —— uv 日常使用指南

3.1 创建一个新项目

# 初始化项目
uv init my-project
cd my-project

uv 会自动生成以下文件结构：

my-project/
├── .git/
├── .gitignore
├── .python-version      # 指定 Python 版本
├── README.md
├── main.py              # 示例 Hello World
└── pyproject.toml       # 项目配置 + 依赖声明

第一次执行 uv run 后，还会自动生成：

├── .venv/               # 虚拟环境
└── uv.lock              # 依赖锁文件

3.2 管理依赖

# 添加依赖（自动更新 pyproject.toml + uv.lock + 虚拟环境）
uv add flask requests

# 指定版本
uv add 'requests==2.31.0'

# 添加 Git 依赖
uv add git+https://github.com/psf/requests

# 移除依赖
uv remove requests

# 升级指定包
uv lock --upgrade-package requests

3.3 运行项目和命令

# 运行主程序（自动检查锁文件 + 同步环境）
uv run main.py

# 运行任意命令
uv run -- flask run -p 3000

# 手动同步环境（不运行命令）
uv sync

# 手动激活虚拟环境
source .venv/bin/activate

注意： uv run 会在每次执行前自动检查 pyproject.toml 和 uv.lock 是否同步，确保环境始终是最新的。

3.4 运行临时工具（uvx）

不需要全局安装就能运行 Python CLI 工具：

# 用 uvx（uv tool run 的别名）一键运行
uvx ruff check .
uvx pycowsay "hello world!"
uvx black my_project/

工具会在临时隔离环境中执行，不污染系统 Python。

如果某个工具需要频繁使用，也可以安装到全局：

uv tool install ruff
ruff --version  # 之后可直接调用

3.5 兼容 pip 接口

如果你暂时不想改变 pip 的使用习惯，uv 提供了完全兼容的 pip 接口：

# 创建虚拟环境
uv venv

# 编译依赖（替代 pip-tools 的 pip-compile）
uv pip compile requirements.in --universal -o requirements.txt

# 安装依赖（替代 pip install）
uv pip sync requirements.txt

这样可以在不修改现有工作流的情况下，直接获得 uv 的性能提升。

3.6 构建和发布

# 构建包
uv build

# 发布到 PyPI
uv publish

四、注意事项

4.1 缓存管理

uv 的全局缓存是它高性能的关键，但也需要注意管理：

# 查看缓存大小和详情
uv cache dir

# 清理整个缓存
uv cache clean

# 智能清理 —— 移除未引用的缓存条目（推荐）
uv cache prune

建议： 定期执行 uv cache prune，尤其是在 CI/CD 环境中，避免缓存无限膨胀。cache prune 会保留当前被项目引用的缓存，只清理废弃部分，比 cache clean 更安全。

4.2 锁文件的正确使用

  • uv.lock 应该提交到 Git —— 确保团队成员和 CI 使用完全一致的依赖版本
  • 不要手动编辑锁文件 —— 它由 uv 自动生成和管理
  • 升级单个包时，用 uv lock --upgrade-package <包名>，而不是全量升级

4.3 兼容性注意事项

  • uv 的 pip 子命令是兼容接口，但扩展了一些额外参数（如 --universal 生成跨平台锁文件），这些是标准 pip 不支持的
  • 某些依赖如果包含非标准安装逻辑（如复杂的 setup.py），可能需要在 uv 中使用 --no-build-isolation 等参数处理
  • uv 的依赖解析器比 pip 更严格，如果 pip 能装但 uv 报错，通常是你的依赖版本约束本身有冲突（pip 只是默默忽略了）

4.4 Python 版本的切换

  • uv python pin 写入的是项目根目录的 .python-version 文件，只影响当前项目
  • 如果需要全局切换，可以设置环境变量 UV_PYTHON 或使用系统的 Python 管理工具配合
  • uv 下载的 Python 解释器存储在全局目录中（通常在 ~/.local/share/uv/python 或 %LOCALAPPDATA%\uv\python），多个项目可共享

4.5 CI/CD 中的使用

在 CI 环境中推荐的最佳实践：

# GitHub Actions 示例
- uses: astral-sh/setup-uv@v3
  with:
    version: "latest"

- run: uv sync --frozen  # 使用已存在的锁文件，不更新
- run: uv run pytest
  • 使用 --frozen 标志确保 CI 严格使用锁文件中的版本，不触发任何解析
  • 配置缓存 key 缓存 uv 的全局缓存目录，加速后续构建

4.6 Windows 支持

uv 完整支持 Windows（包括 PowerShell），但在 Windows 上：

  • 虚拟环境的激活脚本位于 .venv\Scripts\activate
  • Python 下载路径为 %LOCALAPPDATA%\uv\python
  • 部分 Unix-only 的路径操作可能需要注意

结语

uv 不是一个"玩具级"的新工具，它已经具备了生产环境可用的成熟度。凭借 Rust 带来的极致性能、全面的功能覆盖，以及背后 Astral 团队的持续迭代（他们做 Ruff 的成功已经证明了实力），uv 很可能就是 Python 工具链的下一代标准。

如果你还在用 pip + virtualenv + pip-tools 的组合拳，不妨花 10 分钟试试 uv init 和 uv add，感受一下什么叫秒级依赖安装。

参考链接：

posted @ 2026-06-16 09:34  LinLinGOGO  阅读(1)  评论(0)    收藏  举报