uv 教程：快速上手新一代 Python 工具链

前言

Python 生态系统持续演进，辅助开发者高效管理项目的工具亦随之发展。本文将深入探讨 uv，这是由 Astral（Ruff linter 的创建者）推出的一款创新工具，旨在革新 Python 包管理和环境管理。对于寻求 pip、venv、virtualenv、pip-tools 乃至 pyenv 部分功能的高效、集成替代方案的开发者而言，uv 值得关注。

uv 采用 Rust 编写，核心设计目标之一便是极致的速度。然而，速度并非其唯一亮点。uv致力于为众多常见的 Python 开发任务提供一个全面、统一的解决方案。

`uv` 的核心设计理念

极致性能： Rust 的运用使得 uv 在依赖解析、包下载和安装等操作上展现出卓越的速度，显著优于现有的 Python 工具。
统一体验： uv 将 Python 版本管理、项目初始化、依赖管理、脚本执行、工具运行以及构建和发布等功能整合至单一命令行界面，从而减少了工具切换的开销。
现代 Python 实践： 强调通过 pyproject.toml 进行项目配置，并引入了稳定可靠、跨平台的 uv.lock 锁文件机制。
向后兼容性（适度）： uv pip 子命令提供了与 pip 和 pip-tools 常用工作流高度兼容的接口，便于用户迁移，但其目标并非成为 pip 的精确复制品。

安装与配置 `uv`

在深入了解其功能之前，首先介绍如何安装和配置 uv。

安装 `uv`

uv 提供了多种安装方式，以适应不同的操作系统和个人偏好。

独立安装脚本 (推荐): 这是最直接且跨平台一致的安装方法。
- macOS 和 Linux: 打开终端，运行以下任一命令：
BASH
```
# 使用 curl
curl -LsSf https://astral.sh/uv/install.sh | sh
# 或者，如果系统中没有 curl，使用 wget
# wget -qO- https://astral.sh/uv/install.sh | sh
```
要安装特定版本 (例如 0.7.5):
BASH
```
curl -LsSf https://astral.sh/uv/0.7.5/install.sh | sh
```
- Windows (PowerShell): 打开 PowerShell，运行：
POWERSHELL
```
 powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
要安装特定版本 (例如 0.7.5):
POWERSHELL
```
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/0.7.5/install.ps1 | iex"
```
默认情况下，uv 会安装到用户 bin 目录 (如 ~/.local/bin)，安装脚本通常会自动尝试将其添加到 PATH。可以通过设置 UV_INSTALL_DIR 环境变量来自定义安装路径，或通过 INSTALLER_NO_MODIFY_PATH=1 来禁止脚本修改 shell 配置文件。
通过 PyPI (使用 pipx 或 pip): 建议使用 pipx 将 uv 安装到隔离环境中：
BASH
```
pipx install uv
```
或者使用 pip（不推荐全局安装）：
BASH
```
pip install uv
```
注意：如果当前平台没有预编译的 wheel，pip 会尝试从源码构建 uv，这需要一个 Rust 工具链。

其他包管理器:

Homebrew (macOS):

brew install uv

WinGet (Windows):

winget install --id=astral-sh.uv -e

Scoop (Windows):

scoop install main/uv

Cargo (需要 Rust 环境):

cargo install --git https://github.com/astral-sh/uv uv

Docker 镜像: uv 提供官方 Docker 镜像，例如 ghcr.io/astral-sh/uv:latest 或特定版本的 ghcr.io/astral-sh/uv:0.7.5。

安装完成后，通过 uv --version 或 uv self version 验证安装。

更新 `uv`

如果使用独立安装脚本安装：

uv self update
# uv self update <version> # 更新到特定版本

如果使用其他包管理器安装，请使用该管理器相应的更新命令 (如 pipx upgrade uv)。

Shell 自动补全

为 uv 和 uvx 命令启用 shell 自动补全可以极大提高使用效率。例如，对于 Bash：

echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc
echo 'eval "$(uvx --generate-shell-completion bash)"' >> ~/.bashrc
# 对于 Zsh, Fish, PowerShell 等，请参考官方文档中的相应命令

完成上述操作后，重启 shell 或重新加载配置文件。

配置 `uv`

uv 的行为可以通过多种方式进行配置，优先级从高到低如下：

命令行参数。
环境变量： 以 UV_ 开头，例如 UV_INDEX_URL。
项目级配置文件：
- pyproject.toml 文件中的 [tool.uv] 表。
- 项目根目录下的 uv.toml 文件 (若与 pyproject.toml 中的 [tool.uv] 同时存在，uv.toml 优先)。
用户级配置文件： 例如 ~/.config/uv/uv.toml (Linux/macOS)。
系统级配置文件： 例如 /etc/uv/uv.toml。

用户级和系统级配置必须使用 uv.toml 格式。配置会进行合并，项目级优先于用户级，用户级优先于系统级。

禁用配置发现： 使用 --no-config 命令行参数。
指定特定配置文件： 使用 --config-file /path/to/my-uv.toml。
.env 文件加载 (用于 uv run)： uv run 可以通过 --env-file 或 UV_ENV_FILE 加载 .env 文件中的环境变量。

`uv` 的核心功能深度解析

1. Python 版本管理 (`uv python ...`)

uv 对 Python 解释器本身的管理是其一大亮点。

托管与系统 Python： uv 能够发现并使用系统上已有的 Python 安装（“系统 Python”），也能自行下载和安装 Python 版本（“托管 Python”）。
Python 分发源： uv 依赖 Astral 的 python-build-standalone 项目来获取预编译的 CPython 二进制文件，并从 PyPy 官方项目获取 PyPy。
按需安装与版本请求： 通过 --python 标志，可在大多数 uv 命令中请求特定的 Python 版本。支持的格式非常灵活。如果请求的版本在本地不可用，uv 默认会自动下载并安装。
.python-version 文件集成： uv 支持 .python-version 文件来声明项目或全局的默认 Python 版本。uv python pin 命令可以方便地创建这些文件。
BASH
```
uv python pin 3.12 # 在当前目录创建 .python-version
uv python pin --global 3.11 # 创建全局 .python-version
```
可执行文件安装 (预览)： uv python install 3.12 --preview 可以将 python3.12 等可执行文件安装到用户路径下。

2. 项目与工作空间管理

uv 对项目的管理以 pyproject.toml 为核心，并引入了工作空间（Workspaces）的概念。

项目初始化 (uv init)： 快速创建新项目。

uv init my_app # 创建应用项目
uv init --lib my_library # 创建库项目

依赖声明： 在 pyproject.toml 的 [project.dependencies]、[project.optional-dependencies] (extras) 以及 [dependency-groups] (PEP 735, 如 dev 组) 中声明。[tool.uv.sources] 允许为特定依赖指定备用源。
BASH
```
uv add requests
uv add --dev pytest
```
uv.lock – 通用锁文件： uv lock 生成的 uv.lock 文件是跨平台的，记录了确切的依赖版本。
自动锁定与同步： uv run 和 uv sync 命令在执行前会自动检查并更新 uv.lock 和 .venv 虚拟环境。
BASH
```
uv sync
uv lock --upgrade # 升级所有包并更新锁文件
```
工作空间 ([tool.uv.workspace])： 允许将多个相关的 Python 包作为一个单元进行管理，共享同一个 uv.lock。

3. 脚本执行 (`uv run`)

PEP 723 内联元数据： 对于独立的 Python 脚本，uv run 支持在脚本文件头部通过特殊注释块声明依赖项和 Python 版本要求。
PYTHON
```
# /// script
# requires-python = ">=3.10"
# dependencies = ["requests"]
# ///
import requests
# ...
```
使用 uv add --script my_script.py requests 可自动添加元数据。
即时环境： 运行带有内联元数据的脚本时，uv 会自动创建临时的、隔离的环境。
Shebang 支持： #!/usr/bin/env -S uv run --script。

4. 工具执行与安装 (`uvx`, `uv tool ...`)

uvx <tool_name>： 在临时隔离环境中执行工具，无需永久安装。
BASH
```
uvx ruff check .
```
uv tool install <package_name>： 将工具安装到用户 bin 目录，使其全局可用。
BASH
```
uv tool install black ruff
```
版本与来源控制： uvx ruff@0.3.0 或 uvx --from 'ruff==0.3.0'。

5. `pip` 兼容接口 (`uv pip ...`)

为习惯 pip 工作流的用户提供。

环境创建 (uv venv)：
BASH
```
uv venv .venv --python 3.11
```
环境激活 (uv venv)：
uv 创建的虚拟环境（如 .venv）是标准的，因此激活方式与 venv 或 virtualenv 相同。
- macOS/Linux (Bash/Zsh):
  BASH
```
source .venv/bin/activate
```
- Windows (PowerShell):
  POWERSHELL
```
.\.venv\Scripts\Activate.ps1
```
- Windows (cmd.exe):
  CMD
```
.\.venv\Scripts\activate.bat
```
激活后，shell 提示符会改变，后续的 python 和 pip 命令将作用于此环境。完成后使用 deactivate 退出。
注意： uv 的许多命令（如 uv run, uv sync）会自动检测并使用 .venv，通常无需手动激活。

包安装与卸载：

# 已激活 .venv
uv pip install django
uv pip uninstall django

依赖编译 (uv pip compile)：

uv pip compile requirements.in -o requirements.txt

环境同步 (uv pip sync)：

uv pip sync requirements.txt # 精确同步环境

6. 高效的依赖解析与缓存

PubGrub 解析器： uv 使用 pubgrub-rs 进行依赖解析。
通用解析 (Universal Resolution)： uv lock 默认执行通用解析，生成的 uv.lock 考虑所有平台和 Python 版本。

积极的缓存机制： 对下载的 wheel、构建的 sdist、Git 克隆等进行缓存。

uv cache dir # 查看缓存目录
uv cache clean # 清理所有缓存
uv cache prune --ci # 为 CI 优化缓存

7. 构建与发布

uv build： 调用项目定义的构建后端构建 sdist 和 wheel。
BASH
```
uv build # 构建 sdist 和 wheel 到 dist/
```
uv publish： 将构建好的分发包上传到包索引。
BASH
```
uv publish dist/*
```

关于 uv 更多信息和高级用法，请查阅 uv 官方文档↗。

Thanks for reading!