uv 是什么：

uv 是一个用 Rust 编写的、速度极快的 Python 包安装器和解析器，由 Astral 公司（也就是 ruff 的开发者）开发。它的目标是成为 pip 和 pip-tools 的直接替代品，并提供更快、更友好的用户体验。uv 还集成了虚拟环境管理的功能，类似于 venv 或 conda。

uv 的主要特点：

  1. 极速: 由于使用 Rust 编写并采用了先进的并发和缓存策略，uv 在安装、解析依赖关系时通常比 pip 快得多（官方宣称快 10-100 倍）。
  2. 集成工具: 它将包安装（类似 pip）、依赖锁定（类似 pip-compile）和虚拟环境管理（类似 venv）结合在一个工具中。
  3. pip 兼容性: 它的 uv pip 命令设计为 pip 命令的直接替代品，大部分常用命令和参数都兼容。
  4. 先进的依赖解析: 使用 PubGrub 算法进行依赖解析，与 pip 的回溯解析器类似但速度更快。
  5. 全局缓存: 默认启用全局包缓存，避免重复下载。
  6. 跨平台: 支持 macOS, Linux, 和 Windows。

下面是如何安装和使用 uv 的详细步骤：

快速开始：

Python 版本管理

安装和管理 Python 版本。

1
2
3
4
5
uv python install：安装 Python 版本。
uv python list：查看可用的 Python 版本。
uv python find：查找已安装的 Python 版本。
uv python pin：为当前项目指定使用的 Python 版本。
uv python uninstall：卸载 Python 版本。

项目

创建并管理包含 pyproject.toml 的 Python项目。

1
2
3
4
5
6
uv init：创建一个新项目。
uv add：向项目添加依赖。
uv remove：从项目中移除依赖。
uv sync：同步项目依赖到环境。
uv lock：为项目依赖创建锁文件。
uv run：在项目环境中运行命令。

创建虚拟环境（替代 venv 和 virtualenv）

1
uv venv：创建一个新的虚拟环境。

查看使用环境的文档

管理环境中的包（替代 pip 和 pipdeptree）

1
2
3
4
5
6
7
8

uv pip install：安装包到当前环境。
uv pip show：显示已安装包的详细信息。
uv pip freeze：列出已安装包及其版本。
uv pip check：检查当前环境中的包是否兼容。
uv pip list：列出已安装的包。
uv pip uninstall：卸载包。
uv pip tree：查看环境的依赖树。

实用工具

管理和查看 uv 的状态，如缓存、存储目录，或执行自更新：

1
2
3
4
5
6
uv cache clean：清理缓存条目。
uv cache prune：清理过期的缓存条目。
uv cache dir：显示 uv 缓存目录路径。
uv tool dir：显示 uv 工具目录路径。
uv python dir：显示 uv 安装的 Python 版本路径。
uv self update：将 uv 更新到最新版本。

详细教程

1. 安装 uv

你可以通过多种方式安装 uv：

  • 使用 curl (macOS, Linux):

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

  • 使用 pip (需要先有 Python 和 pip):

    1
    pip install uv

    使用 Homebrew (macOS):

    1
    brew install uv

  • 使用 Scoop (Windows):

    1
    scoop install uv

  • 使用 Winget (Windows):

    1
    winget install astral.uv

安装完成后，可以通过运行以下命令来验证：

1
uv --version

2. 创建和管理虚拟环境

uv 使用 uv venv 命令来创建虚拟环境，这类似于 Python 内置的 venv 模块。

  • 创建虚拟环境:

    1
    2
    3
    4
    5
    6
    7
    8
    # 创建一个名为 .venv 的虚拟环境 (这是常见的命名约定)
    uv venv

    # 也可以指定环境名称
    uv venv my_env_name

    # 还可以指定 Python 解释器版本 (如果系统中有多个)
    uv venv -p 3.11 # 使用 Python 3.11

    这会在当前目录下创建一个 .venv (或你指定的名字) 的文件夹。

  • 激活虚拟环境:
    创建环境后，你需要激活它才能使用。激活方式与 venv 相同：

    • macOS / Linux (bash/zsh):
      1
      source .venv/bin/activate
    • Windows (cmd.exe):
      1
      .venv\Scripts\activate.bat
    • Windows (PowerShell):
      1
      .venv\Scripts\Activate.ps1
      激活后，你的命令行提示符通常会显示环境名称（例如 (.venv)）。

  • 退出虚拟环境:

    1
    deactivate

3. 安装 Python 包

uv 使用 uv pip install 命令来安装包，用法与 pip install 非常相似。请确保你已经激活了虚拟环境。

  • 安装单个包:

    1
    2
    3
    4
    5
    6
    7
    8
    # 安装最新版本的 requests 包
    uv pip install requests

    # 安装特定版本的 requests 包
    uv pip install requests==2.28.1

    # 安装最低版本要求
    uv pip install requests>=2.20

  • 安装多个包:

    1
    uv pip install requests flask Django

  • 从 requirements.txt 文件安装:
    这是管理项目依赖的常用方式。

    1
    2
    3
    4
    5
    6
    # 假设你有一个 requirements.txt 文件
    # 内容类似:
    # requests==2.28.1
    # flask>=2.0

    uv pip install -r requirements.txt

    uv 会读取文件并安装所有指定的包及其依赖。

  • 安装带 “extras” 的包:

    1
    uv pip install "package[extra1,extra2]"

  • 安装开发依赖:
    通常将开发依赖放在不同的文件（如 requirements-dev.txt）中。

    1
    uv pip install -r requirements-dev.txt

4. 同步环境 (uv pip sync)

uv pip sync 是一个非常有用的命令，它能确保你的虚拟环境精确匹配 requirements.txt 文件中的内容。

  • 它会安装 requirements.txt 中列出的所有包。
  • 它会卸载虚拟环境中已安装但未在 requirements.txt 中列出的包。

这对于保持环境干净、可复现非常重要。

1
2
3
4
5
# 确保环境与 requirements.txt 完全一致
uv pip sync requirements.txt

# 如果有开发依赖，可以同时同步多个文件
uv pip sync requirements.txt requirements-dev.txt

对比: uv pip install -r requirements.txt 只会安装或更新包，不会删除多余的包，而 uv pip sync 会严格同步。

5. 查看已安装的包

  • 列出已安装的包 (简单列表):

    1
    uv pip list

  • 冻结依赖 (生成 requirements.txt 格式):
    这个命令会输出当前环境中所有已安装的包及其精确版本，非常适合用来生成 requirements.txt 文件。

    1
    uv pip freeze > requirements.txt

6. 卸载包

  • 卸载单个或多个包:

    1
    uv pip uninstall requests flask

  • 从 requirements.txt 卸载:

    1
    uv pip uninstall -r requirements.txt

7. 生成依赖锁定文件 (pip-compile 的替代)

uv 也提供了类似 pip-tools 中 pip-compile 的功能，用于生成固定的依赖版本文件。这通常用于更严格的依赖管理，确保每次安装都使用完全相同的版本。

  • 从 pyproject.toml 或 requirements.in 生成 requirements.txt:
    假设你的 pyproject.toml 文件中有如下依赖定义：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    [project]
    name = "my-package"
    version = "0.1.0"
    dependencies = [
      "flask>=2.0",
      "requests",
    ]

    [project.optional-dependencies]
    dev = [
      "pytest",
    ]

    或者你有一个 requirements.in 文件：

    1
    2
    flask>=2.0
    requests

    你可以运行：

    1
    2
    3
    4
    5
    6
    7
    8
    # 从 pyproject.toml 生成 requirements.txt (默认)
    uv pip compile pyproject.toml -o requirements.txt

    # 或者从 requirements.in 生成
    uv pip compile requirements.in -o requirements.txt

    # 生成开发依赖的锁定文件
    uv pip compile pyproject.toml --extra dev -o requirements-dev.txt

    这会解析所有子依赖，并生成一个包含所有包精确版本的 requirements.txt (或 -dev.txt) 文件。然后你可以使用 uv pip sync 来安装这些锁定的依赖。

8. 在虚拟环境中运行命令 (uv run)

如果你不想激活虚拟环境，但想在其中执行某个命令（比如运行你的 Python 脚本），可以使用 uv run：

1
2
3
4
5
6
# 假设你在项目根目录，并且 .venv 存在
# 运行你的 main.py 脚本
uv run python main.py

# 运行 pytest 测试
uv run pytest

uv run 会自动检测 .venv 目录，并在该环境中执行后续命令。

总结：为什么使用 uv？

  • 速度: 最显著的优势，能大幅节省安装和管理依赖的时间。
  • 简洁: 将多个工具（pip, venv, pip-tools）的功能整合到一个命令行工具中。
  • 现代: 采用更现代、高效的技术栈（Rust, PubGrub）。
  • 易用性: 旨在提供比 pip 更友好的错误提示和用户体验。
  • 兼容性: uv pip 命令与 pip 高度兼容，迁移成本低。

uv 是一个非常有前途的工具，特别适合那些对性能有要求或者希望简化 Python 环境和依赖管理流程的开发者。虽然它还在快速发展中，但已经足够稳定，可以在许多项目中使用。