Python UV：最快速的 Python 包管理器终极指南

什么是 Python UV？

UV 是一款以 Rust 编写的现代高性能 Python 包管理与安装工具。它可直接替代传统的 Python 包管理工具如 pip，在速度、可靠性和依赖解析方面有显著提升。

该工具代表了新一代的 Python 包管理器，旨在解决 Python 生态中的常见痛点，例如安装耗时长、依赖冲突以及环境管理复杂等问题。UV 通过创新架构与高效实现达成目标，其性能较传统包管理器快 10–100 倍。

UV 脱颖而出的关键特性：

• 闪电般快速的包安装与依赖解析
• 兼容现有的 Python 工具与工作流
• 内置虚拟环境管理
• 支持现代打包标准
• 可靠的依赖锁定与可复现环境
• 内存占用低，尤其适用于大型项目

无论是小型个人项目，还是大型 Python 应用的管理，UV 都能提供稳健高效的包管理方案。在本教程中，我们将涵盖 UV 的核心用法，帮助您即刻上手。

摘要

• UV 是一款由 Rust 驱动的 Python 包管理器，比 pip 快 10–100 倍
• 安装命令：curl -LsSf https://astral.sh/uv/install.sh | sh
• 用 uv init 初始化项目，用 uv add package 添加依赖
• 用 uv run script.py 运行脚本——无需手动激活虚拟环境
• UV 将 pip、virtualenv、pyenv 与 pip-tools 的功能整合于一体
• 锁文件（uv.lock）确保跨机器环境可复现
• 使用 uvx 运行 black、ruff 等 CLI 工具，无需永久安装

UV、Poetry、PIP、Conda 与 virtualenv 的差异

在切换到新工具前，开发者通常会先问：“和我现在用的相比如何？”在 Python 的依赖与项目管理领域，下列四个工具最为常见：

• PIP
• Poetry
• Conda
• virtualenv

在深入细节之前，让我们将 UV 与这些工具逐一对比，帮助您判断 UV 是否适合您的需求。

UV vs. PIP 与 virtualenv

PIP 与 virtualenv 是传统的 Python 包管理与虚拟环境创建工具。虽然它们能完成任务，但 UV 具有多项令人信服的优势：

• 速度：UV 采用 Rust 实现，使其在安装包与解析依赖时显著快于 PIP，常见任务在 UV 上仅需数秒，而 PIP 可能需数分钟。
• 一体化环境管理：virtualenv 只负责环境创建、PIP 只负责包管理，而 UV 将两者合二为一，显著简化工作流。

UV 在完全兼容 PIP 生态的同时解决其关键局限。它可直接使用同样的 requirements.txt 文件与包索引，实现无缝迁移。主要差异在于：

• 性能：并行下载与优化的依赖解析器让 UV 在大型项目中比 PIP 快 10–100 倍。
• 内存占用：在安装与解析依赖时，UV 的内存使用显著低于 PIP。
• 错误处理：当依赖冲突时，UV 提供更清晰的错误信息和更好的冲突解决。
• 可复现性：UV 的锁文件方案确保跨系统环境一致，而基础的 requirements.txt 并不能保证。

尽管 PIP 与 virtualenv 依然可用，但 UV 的现代架构与一体化功能，使其对追求更高性能与更顺畅工作流的开发者极具吸引力。UV 能够在不打乱既有流程的前提下接入现有项目，这对打算逐步现代化 Python 开发工具链的团队尤其有益。

UV vs. Conda

不使用 PIP 与 virtualenv 的人往往会选择 Conda，且理由充分：

• Conda 提供完整的包管理方案，不仅能管理 Python 包，还能处理系统级依赖
• 在管理包含 NumPy、SciPy、TensorFlow 等的科学计算环境方面表现出色
• Conda 环境在不同操作系统之间更为隔离且易于复现
• 内置对不同 Python 版本的支持，并可轻松切换
• Anaconda 发行版预装了大量科学计算包，便于数据科学家上手

但即便是资深 Conda 用户，也应因多种原因考虑切换到 UV。（关于更广泛的环境管理工具比较，参见 Anaconda vs Python: Exploring Their Differences。）UV 的极速安装与依赖解析可显著加快环境搭建，相比 Conda 偶尔偏慢的表现优势明显。其轻量资源占用意味着更低的内存使用与更快的启动。UV 还能与现有的 Python 打包标准与工具无缝集成，更易融入更广泛的 Python 生态。对于不需要 Conda 管理非 Python 包的项目，UV 提供更简洁高效的方案，能显著改善开发工作流。

UV vs. Poetry

我使用 Conda 近三年，几次尝试 Poetry 后，就再也没碰过“龟速”的 Conda。正当我对 Poetry 感到顺手时，遇到了 UV，而它提供的能力几乎与 Poetry 等同：

• 依赖管理：两者都能高效处理包依赖与虚拟环境
• 项目结构：两者都提供初始化与组织 Python 项目的工具
• 锁文件：两者都会生成锁文件，保证环境可复现
• 包发布：两者都支持发布到 PyPI
• 现代化工具链：两者都代表了现代的 Python 项目管理方式

然而，UV 的决定性优势在于极致的速度与极低的资源占用。虽然 Poetry 相比传统工具已有长足进步，但得益于 Rust 实现，UV 将性能提升到新的高度。此外，UV 与现有 Python 打包生态的兼容性更强，能与 pip 等工具协同工作，在灵活性上有时优于 Poetry 更为“主观化”的做法。

下表对我们刚讨论的差异做了总结：

如果您认为 UV 值得一试，请继续往下读。

在 Python 项目中开始使用 UV

本节介绍如何使用 UV 从零开始一个项目。若您需要先搭建 Python 开发环境，请参考我们的专门指南。我们会在后文讨论如何从现有项目迁移到 UV。

安装 UV

在 macOS 与 Linux 上可使用 cURL 进行系统范围安装：

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

在 Windows 上使用 Powershell（请确保以管理员权限运行 Powershell）：

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

UV 也可通过 Homebrew 安装：

$ brew install uv

亦可通过 PIP 安装，但不推荐：

$ pip install uv  # Make sure you have a virtual environment activated

随后，运行 uv version 验证安装：

$ uv version
uv 0.6.14 (2026-03-13)

更新 UV

通过独立安装器安装的 UV 可自更新：

$ uv self update

如果是通过 Homebrew 安装，请使用 brew upgrade uv。您也可以为 UV 命令启用 shell 自动补全：

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

初始化新项目

围绕项目开展工作是 UV 体验的核心。首先使用 uv init 命令初始化一个空项目：

$ uv init explore-uv
Initialized project explore-uv at /Users/bexgboost/projects/explore-uv

该命令会立即创建一个新的 explore-uv 目录，包含以下内容：

$ cd explore-uv
$ tree -a
.
├── .gitignore
├── .python-version
├── README.md
├── hello.py
└── pyproject.toml

Git 会自动初始化，并生成主要的与 Git 相关文件，如 .gitignore 与空白 README.md。.python-version 文件记录项目所用的 Python 版本，而 pyproject.toml 则是项目元数据与依赖的主要配置文件。同时会创建示例文件 hello.py，帮助您快速上手。

您可以从 UV 文档了解更多项目创建相关内容。

为项目添加初始依赖

UV 将环境创建与依赖安装合并为一个命令——uv add：

$ uv add scikit-learn xgboost
Using CPython 3.9.20 interpreter at: /opt/homebrew/opt/python@3.9/bin/python3.9
Creating virtual environment at: .venv
Resolved 6 packages in 1.78s
⠧ Preparing packages... (2/5)
Prepared 5 packages in 1m 23s
Installed 5 packages in 45ms
 + joblib==1.4.2
 + numpy==2.0.2
 + scikit-learn==1.5.2
 ...

第一次运行 add 命令时，UV 会在当前工作目录下创建新的虚拟环境并安装指定依赖。后续运行中，UV 会复用已存在的虚拟环境，仅安装或更新新请求的包，从而确保高效的依赖管理。

每次执行 add 命令时，另一个重要过程是依赖解析。UV 使用现代依赖解析器，分析完整依赖图，寻找满足所有需求的兼容版本组合。这有助于防止版本冲突并确保环境可复现。解析器会综合考虑版本约束、Python 版本兼容性以及平台特定需求，确定要安装的最优包集合。

UV 还会在每次添加后更新 pyproject.toml 与 uv.lock 文件。以下是安装 Scikit-learn 与 XGBoost 后的 TOML 文件示例：

$ cat pyproject.toml
[project]
name = "explore-uv"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.9"
dependencies = [
    "scikit-learn>=1.5.2",
    "xgboost>=2.0.3",
]

要从环境与 pyproject.toml 中移除依赖，可使用 uv remove 命令。它会卸载该包及其所有子依赖：

$ uv remove scikit-learn

我们将在后文更详细讨论依赖管理。

使用 UV 运行 Python 脚本

安装必要依赖后，您即可像往常一样编写 Python 脚本。若使用 VS Code，可参考我们关于为 Python 设置 VS Code的指南。UV 提供多种运行 Python 代码的方式：

要直接运行 Python 脚本，可使用 uv run 命令并跟上脚本名，代替常见的 python script.py 语法：

$ uv run hello.py

run 命令可确保脚本在 UV 为项目创建的虚拟环境中执行。

运行包含内联依赖的脚本（PEP 723）

UV 支持 PEP 723 的脚本内联元数据，允许您在 Python 脚本中直接声明依赖。这对于无需完整项目设置的独立脚本非常有用：

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

import requests
from rich.console import Console

console = Console()
response = requests.get("https://api.github.com")
console.print(f"GitHub API status: [bold green]{response.status_code}[/bold green]")

使用 uv run 运行脚本后，UV 会自动创建一个带有声明依赖的隔离环境：

$ uv run script.py
GitHub API status: 200

这对于与同事共享可复现脚本尤其强大——只要安装了 UV，任何人都无需手动安装依赖即可运行该脚本。

在 UV 中管理 Python 版本

Python 版本管理是依赖管理的重要组成部分。UV 提供简单命令来控制使用的 Python 版本。下面介绍如何使用 uv python 命令。

使用 UV 安装 Python 版本

UV 可直接安装与管理 Python 版本，从而替代 pyenv 等工具：

$ uv python install 3.12
$ uv python install 3.11 3.13  # Install multiple versions at once

Python 安装位置位于 ~/.local/share/uv/python/，不会影响系统自带的 Python。您也可以将项目固定到特定 Python 版本：

$ uv python pin 3.12

这会更新项目目录下的 .python-version 文件。此后 UV 将在所有项目操作中使用该版本。

列出现有 Python 版本

由于系统常已安装了 Python，UV 默认会发现这些现有安装。要列出系统上 UV 检测到的所有 Python 版本，运行以下命令：

$ uv python list --only-installed
cpython-3.13.0-macos-aarch64-none     /opt/homebrew/opt/python@3.13/bin/python3.13 -> ../Frameworks/Python.framework/Versions/3.13/bin/python3.13
cpython-3.12.7-macos-aarch64-none     /opt/homebrew/opt/python@3.12/bin/python3.12 -> ../Frameworks/Python.framework/Versions/3.12/bin/python3.12
cpython-3.12.5-macos-aarch64-none     /Users/bexgboost/miniforge3/bin/python3.12
cpython-3.12.5-macos-aarch64-none     /Users/bexgboost/miniforge3/bin/python3 -> python3.12
cpython-3.12.5-macos-aarch64-none     /Users/bexgboost/miniforge3/bin/python -> python3.12
cpython-3.11.10-macos-aarch64-none    /opt/homebrew/opt/python@3.11/bin/python3.11 -> ../Frameworks/Python.framework/Versions/3.11/bin/python3.11
cpython-3.11.7-macos-aarch64-none     /Users/bexgboost/.local/share/uv/python/cpython-3.11.7-macos-aarch64-none/bin/python3 -> python3.11
cpython-3.10.15-macos-aarch64-none    /opt/homebrew/opt/python@3.10/bin/python3.10 -> ../Frameworks/Python.framework/Versions/3.10/bin/python3.10
cpython-3.9.20-macos-aarch64-none     /opt/homebrew/opt/python@3.9/bin/python3.9 -> ../Frameworks/Python.framework/Versions/3.9/bin/python3.9
cpython-3.9.6-macos-aarch64-none      /Library/Developer/CommandLineTools/usr/bin/python3 -> ../../Library/Frameworks/Python3.framework/Versions/3.9/bin/python3

该命令正确检测到了我通过 Conda 与 Brew 安装的 Python 版本。

为当前项目更换 Python 版本

只要新版本满足 pyproject.toml 中的规格要求，您可随时为当前 UV 项目切换 Python 版本。例如，以下文件要求 Python 版本为 3.9 及以上：

...
requires-python = ">=3.9"

这意味着您可以将 .python-version 中的版本改为任一更高版本，如 3.11.7。之后调用 uv sync。

命令会先检查现有 Python 安装；若未找到请求的版本，UV 会下载并安装到 /Users/username/.local/share/uv/python 路径中。UV 还会在项目目录内创建新的虚拟环境，替换旧环境。

uv sync 会自动处理一切——创建新虚拟环境，并根据 pyproject.toml 与 uv.lock 重新安装所有依赖，无需额外的安装步骤。

注意，某些情况下 uv 命令可能报出 Permission Denied 错误。在 macOS 或 Linux 上请使用 sudo，在 Windows 上请以管理员权限运行命令提示符。更好的做法是将 UV 主目录的所有权改为当前用户：

$ sudo chown -R $USER ~/.local/share/uv  # macOS or Linux

关于使用 UV 管理 Python 版本的更多信息，请参阅文档。

什么是 UV Tools，如何使用？

一些 Python 包会以命令行工具的形式提供，如用于代码格式化的 black、用于 Lint 的 flake8、用于测试的 pytest、用于类型检查的 mypy 等。UV 提供两种专用接口来管理这些包：

1. 使用 uv tool run：

$ uv tool run black hello.py

2. 使用更短更便捷的 uvx 命令：

$ uvx black hello.py

运行这些命令时，UV 会在其缓存中创建一个临时虚拟环境，安装并从中运行所请求的工具。换言之，您无需将这些命令行工具安装到项目虚拟环境中即可使用，从而执行更快、依赖更干净。

关于工具运行接口的要点：

• 适用于任何提供命令行工具的 Python 包，如 flake8、mypy、black 或 pytest
• 清理 UV 缓存时，缓存环境会自动清除
• 按需创建新的缓存环境
• 非常适合偶尔使用的开发工具
• 对于经常使用的工具，请用 uv tool install 永久安装：

$ uv tool install ruff
$ uv tool install black
$ ruff check .  # Now available directly in PATH

永久安装的工具可通过全局 PATH 使用，而不会污染任何项目的虚拟环境。可用 uv tool upgrade ruff 更新，用 uv tool list 列出所有已安装工具。

阅读文档中的 UV Tools 章节了解更多这些接口的信息。

UV 中的锁文件是什么？

锁文件（uv.lock）是 UV 依赖管理的关键组成部分。当您运行 uv add 安装依赖时，UV 会自动生成并更新 uv.lock。该锁文件的作用包括：

• 记录所有依赖及其子依赖的确切版本
• 通过“锁定”版本，在不同环境中确保可复现的构建
• 通过保持一致的包版本，帮助避免“依赖地狱”
• 加速安装过程，因为 UV 可直接使用锁定版本而无需再次解析

UV 会自动管理锁文件——无需手动编辑。应将锁文件提交到版本控制，以确保所有开发者使用一致的依赖版本。

锁文件与 requirements.txt 的区别

尽管锁文件与 requirements.txt 都用于追踪依赖，但用途与场景不同。锁文件包含关于精确包版本与完整依赖树的详细信息，确保开发环境一致。Requirements.txt 相对简单，通常只列出直接依赖，并在 Python 工具间被广泛支持。

在开发阶段，锁文件对于维持可复现构建与避免依赖冲突至关重要。Requirements.txt 更适合部署场景，或与未使用 UV 的用户共享代码时使用。对于不支持 UV 锁文件格式的工具与服务，requirements.txt 也必不可少。

您可以同时维护两者：开发时使用 UV 锁文件，同时生成 requirements.txt 供部署使用。要从 UV 锁文件生成 requirements.txt，请使用：

$ uv export -o requirements.txt

该命令会基于锁文件的固定版本创建文本文件，便于以标准格式共享项目依赖，同时在开发期仍享受 UV 的高级依赖管理能力。

关于管理锁文件的更多信息，请参阅文档。

使用 UV 进行高级依赖管理

本节将探讨在 UV 中进行更复杂依赖管理的方法。我们会学习如何更新依赖、将其设为可选，或将其划入依赖分组。

更新依赖

在长期项目中，常需要更新所用包以获取最新功能；有时某个包引入了破坏性变更，您希望确保该版本不会被意外安装。在这些以及其他需要调整现有依赖的约束或版本的场景中，都可以再次使用 add 命令。

1. 安装包的最新版本：

$ uv add requests

2. 安装特定版本：

$ uv add "requests==2.1.2"

3. 调整包的版本边界：

$ uv add 'requests<3.0.0'

4. 将依赖设为平台特定：

$ uv add 'requests; sys_platform="linux"' 

添加可选依赖

可选依赖并非项目核心功能所必需，但可能用于特定特性。例如，Pandas 提供 excel 与 plot 这类 extra，从而避免在未明确需要时安装 Excel 解析器与 matplotlib。通常通过 pip install pandas[plot, excel] 的语法安装可选项。

在 UV 中，语法略有不同。首先，确保已安装 Pandas 主包：

$ uv add pandas

然后使用方括号标注安装其可选 extra：

$ uv add "pandas[plot,excel]"

解析完成后，它们会以如下格式出现在 pyproject.toml 中：

[project]
name = "explore-uv"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.9"
dependencies = [
    "pandas[plot,excel]>=2.2.3",
    "requests>=2.32.3",
]

依赖分组

依赖分组允许您将依赖按逻辑分组，如开发依赖、测试依赖或文档依赖。这有助于将生产依赖与开发依赖分离。

要将依赖添加到特定分组，请使用 --group 标志：

$ uv add --group group_name package_name

随后，用户可通过 --group、--only-group 与 --no-group 标签来控制安装哪些分组。

从 PIP 与 Virtualenv 切换到 UV

由于 UV 与现有 Python 打包标准兼容，从 PIP 与 virtualenv 迁移到 UV 十分直接。以下是帮助平滑过渡的分步指南：

1. 转换现有 virtualenv 项目

如果您有使用 virtualenv 与 pip 的现有项目，先从当前环境生成 requirements.txt（若尚未生成）：

$ pip freeze > requirements.txt

然后在同一目录中创建新的 UV 项目：

$ uv init .

最后，从 requirements 文件中安装依赖：

$ uv pip install -r requirements.txt

2. 用 UV 等价命令替换常见 pip/virtualenv 命令

以下是常见 pip 与 virtualenv 命令及其 UV 等价用法速查：

迁移完成后，您可以放心删除旧的 virtualenv 目录，开始使用 UV 的虚拟环境管理。此过渡过程通常十分顺畅，必要时您也可通过 UV 的 pip 兼容层回退至 pip 命令。

在 CI/CD 与 Docker 中使用 UV

UV 的高速度在 CI/CD 流水线中尤为有价值，因为每次构建都会安装依赖。以下是一个使用 UV 的 GitHub Actions 工作流示例：

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install uv
        uses: astral-sh/setup-uv@v3
      - name: Set up Python
        run: uv python install 3.12
      - name: Install dependencies
        run: uv sync --frozen --dev
      - name: Run tests
        run: uv run pytest tests/

--frozen 标志确保 CI 严格使用锁文件中的版本，若锁文件过期则构建失败，从而保证构建可复现。

Docker 集成

UV 也能显著加快 Docker 镜像构建：

FROM python:3.12-slim

# Install uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev --no-editable

COPY . .
CMD ["uv", "run", "python", "app.py"]

通过先复制依赖文件并安装，再复制源码，您可充分利用 Docker 层缓存。只有当 pyproject.toml 或 uv.lock 发生变化时，依赖安装步骤才会重新执行。

结语

UV 在 Python 包管理方面实现了重要进步，提供了比传统工具更现代、更快速且更高效的替代方案。其主要优势包括：

• 极速性能，相比 pip 提升 10–100 倍
• 与现有 Python 打包标准无缝集成
• 内置虚拟环境管理
• 高效的依赖解析与锁文件支持
• 低内存与资源占用

无论是新项目还是迁移现有项目，UV 都能显著改善您的 Python 开发工作流。其与现有工具的兼容性，让您在不扰乱当前流程的情况下轻松实现工具链现代化。

随着 Python 生态持续演进，像 UV 这样的工具展示了如何借助 Rust 等现代技术提升开发体验，同时保持 Python 开发者所重视的简洁与易用。

若您希望进一步学习依赖管理或 Python 的更多内容，请参考以下资源：

• Python 入门教程
• PIP Python 教程：权威指南
• Python 包开发课程
• 适用于 Python 环境管理的 9 大 Anaconda 替代方案
• Python 数据科学家 | 学习用于数据科学的 Python
• Python Poetry：现代高效的 Python 环境与依赖管理