uv 使用指导文档
概述
uv 是一个高性能的 Python 包管理和项目管理工具，使用 Rust 编写，速度比传统工具（如 pip、virtualenv 等）快 10-100 倍。它旨在简化 Python 开发工作流，提供依赖管理、虚拟环境管理、脚本运行、工具执行以及项目构建等功能。以下是基于 uv 官网（https://docs.astral.sh/uv/）整理的使用指导，涵盖安装、核心功能及常见用例。
安装 uv
uv 提供了多种安装方式，适用于 macOS、Linux 和 Windows 系统。以下是主要安装方法：
1. 使用独立安装程序
macOS 和 Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
此命令会下载并安装 uv，并将二进制文件添加到用户 PATH 中。
Windows
在 PowerShell 中运行（需要管理员权限）：
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
禁用 PATH 修改
如果不希望安装程序修改 shell 配置文件，可以设置环境变量：
curl -LsSf https://astral.sh/uv/install.sh | env INSTALLER_NO_MODIFY_PATH=1 sh
2. 使用 PyPI 安装
推荐使用 pipx 将 uv 安装到隔离环境中：
pipx install uv
或者使用 pip：
pip install uv
3. 使用 Homebrew 或 Cargo
- Homebrew（macOS/Linux）：
brew install uv - Cargo（需要 Rust 工具链）：
cargo install --git https://github.com/astral-sh/uv uv
4. 自更新
通过独立安装程序安装的 uv 支持自更新：
uv self update
更多安装方式及细节，请参考 uv 安装文档。
核心功能
uv 集成了多种功能，可替代 pip、pip-tools、virtualenv、pipx、poetry 等工具。以下是主要功能及使用方法：
1. 管理虚拟环境
uv 创建虚拟环境的效率远超 python -m venv 和 virtualenv。
创建虚拟环境
uv venv
默认在当前目录创建 .venv 虚拟环境。激活方式因 shell 和平台而异，例如：
- Unix（bash/zsh）：
source .venv/bin/activate - Windows（PowerShell）：
.venv\Scripts\Activate.ps1
指定 Python 版本
uv venv --python 3.12
如果指定的 Python 版本未安装，uv 会自动下载。
2. 安装和管理 Python 版本
uv 支持快速安装和切换 Python 版本，无需手动管理。
安装 Python
uv python install 3.10 3.11 3.12
此命令安装指定版本的 Python，完成后可通过 uv python list 查看已安装版本。
固定 Python 版本
在项目目录中固定 Python 版本：
uv python pin 3.11
这会在当前目录创建 .python-version 文件，指定使用 Python 3.11。
自动下载
如果未安装所需的 Python 版本，uv 会自动下载：
uv run --python 3.12 python --version
3. 管理依赖
uv 提供高效的依赖解析和安装功能，支持 requirements.txt 和 pyproject.toml。
安装依赖
在虚拟环境中安装包：
uv pip install requests
编译 requirements.txt
从 requirements.in 生成带固定版本的 requirements.txt：
uv pip compile requirements.in --output-file requirements.txt
同步依赖
确保环境与 requirements.txt 或 uv.lock 一致：
uv pip sync requirements.txt
项目依赖管理
在包含 pyproject.toml 的项目中，添加依赖：
uv add requests
这会更新 pyproject.toml 和 uv.lock 文件，并安装依赖到虚拟环境。
4. 运行脚本
uv 支持运行单文件脚本，并自动管理其依赖。
运行简单脚本
uv run example.py
如果脚本位于项目目录，uv 会自动使用项目的虚拟环境。
带内联依赖的脚本
创建脚本并添加依赖元数据：
echo '# /// script
# requires-python = ">=3.12"
# dependencies = ["requests"]
# ///
import requests
print(requests.get("https://astral.sh"))' > example.py
uv run example.py
uv 会为脚本创建隔离的虚拟环境并安装依赖。
5. 运行和安装工具
uv 可运行和安装命令行工具，类似 pipx。
运行工具
在临时环境中运行工具：
uvx pycowsay 'hello world!'
安装工具
将工具安装到持久环境中：
uv tool install ruff
安装后，工具的可执行文件会添加到 ~/.local/bin（需确保在 PATH 中）。
6. 项目管理
uv 支持完整的 Python 项目管理，包括初始化、构建和发布。
初始化项目
uv init my-project
生成项目结构，包括 pyproject.toml、.gitignore、.python-version 等。
构建项目
uv build
在 dist/ 目录生成 .whl 和 .tar.gz 文件。
发布到 PyPI
uv publish
需配置 PyPI API 令牌。推荐在 pyproject.toml 中设置索引：
[[tool.uv.index]]
name = "testpypi"
url = "https://test.pypi.org/simple/"
publish-url = "https://test.pypi.org/legacy/"
然后发布：
uv publish --index testpypi
7. Docker 集成
uv 优化了在 Docker 中的使用，支持多阶段构建和缓存。
示例 Dockerfile
FROM python:3.12-slim-bookworm
RUN apt-get update && apt-get install -y curl
ADD https://astral.sh/uv/install.sh /uv-installer.sh
RUN sh /uv-installer.sh && rm /uv-installer.sh
ENV PATH="/root/.local/bin/:$PATH"
ADD . /app
WORKDIR /app
RUN uv sync --locked
建议将 .venv 添加到 .dockerignore 以避免包含本地虚拟环境。
高级功能
1. 工作空间支持
uv 支持 Cargo 风格的工作空间，适合管理多个相关项目：
uv add --workspace requests
这会在工作空间根目录的 pyproject.toml 中添加依赖。
2. 缓存优化
uv 使用全局缓存（位于 ~/.cache/uv 或可通过 UV_CACHE_DIR 自定义）以减少重复下载。
3. Git 依赖
支持从 Git 仓库安装包：
uv pip install "git+https://github.com/astral-sh/ruff@main"
4. 字节码编译
优化启动时间：
uv pip install requests --compile-bytecode
或设置环境变量 UV_COMPILE_BYTECODE=1。
注意事项
- 虚拟环境优先：uv 强烈推荐使用虚拟环境，避免修改系统 Python 环境（需使用
--system标志）。 - 锁文件：
uv.lock是 uv 管理的文件，禁止手动编辑。 - 兼容性：uv 的
pip接口与传统 pip 命令兼容，但速度更快。 - 社区支持：uv 由 Astral 开发，文档和社区资源丰富，详见 GitHub 和 Astral 官网。
总结
uv 是一个功能强大、性能优越的 Python 工具，集成了包管理、虚拟环境管理、脚本运行和项目构建等功能。通过其快速的依赖解析和简化的工作流，uv 大幅提升了 Python 开发效率。无论是开发单文件脚本还是复杂项目，uv 都能提供高效支持。更多详细信息，请访问 uv 官方文档。