uv 完全指南

官方文档：https://docs.astral.sh/uv/
适用版本：uv 0.4+（2026-05-07 核实）

uv 是由 Astral（Ruff 的开发团队）用 Rust 编写的 Python 包管理器和项目管理工具。它将 pip、pip-tools、pipx、pyenv、virtualenv 的功能集成到一个工具中，速度比 pip 快 10-100 倍。

相关文档：Python包管理工具 | FastAPI完全指南 | pytest完全指南

基础概念

uv 的定位

uv 是一个"全能型"Python 工具链，可替代多个现有工具：

核心文件

uv.lock 说明

uv.lock 是跨平台锁定文件，记录所有 Python 标记（操作系统、CPU 架构、Python 版本）下会安装的精确版本。格式为人类可读的 TOML，但不应手动编辑。

与 requirements.txt 的区别：uv.lock 包含所有平台的信息，而 requirements.txt 只记录当前平台的安装结果。

安装

安装方式

# 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"

# 安装指定版本
curl -LsSf https://astral.sh/uv/0.6.0/install.sh | sh

# 通过 Homebrew（macOS/Linux）
brew install uv

# 通过 pip（不推荐，但可用）
pip install uv

# 通过 pipx
pipx install uv

自更新与卸载

# 更新到最新版本
uv self update

# 查看版本
uv --version

# 卸载（先清理缓存）
uv cache clean
# 然后删除二进制文件（通常在 ~/.cargo/bin/uv 或 ~/.local/bin/uv）

Shell 补全

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

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

# Fish
echo 'uv generate-shell-completion fish | source' >> ~/.config/fish/config.fish

# PowerShell
Add-Content $PROFILE '(& uv generate-shell-completion powershell) | Out-String | Invoke-Expression'

Python 版本管理

uv 内置 Python 版本管理，无需 pyenv 等额外工具。

uv python install

安装指定 Python 版本（来自 python-build-standalone 项目）。

uv python install [OPTIONS] [TARGETS]...

# 安装最新 Python 3.12
uv python install 3.12

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

# 安装 PyPy
uv python install pypy3.10

# 安装特定补丁版本
uv python install 3.12.3

uv python list

列出可用和已安装的 Python 版本。

uv python list [OPTIONS]

uv python list
uv python list --only-installed
uv python list --all-versions

uv python pin

固定项目使用的 Python 版本，写入 .python-version 文件。

uv python pin [OPTIONS] [REQUEST]

uv python pin 3.12
uv python pin 3.12.3 --resolved

uv python find

查找匹配条件的 Python 解释器路径。

uv python find [REQUEST]

uv python find 3.12
# 输出：/home/user/.local/share/uv/python/cpython-3.12.3-.../bin/python3

uv python uninstall

卸载已安装的 Python 版本。

uv python uninstall [TARGETS]...

uv python uninstall 3.11
uv python uninstall --all  # 卸载所有 uv 管理的 Python

uv python upgrade

升级已安装的 Python 到最新补丁版本。

uv python upgrade 3.12  # 升级 3.12.x 到最新补丁
uv python upgrade --all  # 升级所有已安装版本

Python 版本解析优先级

uv 按以下顺序查找 Python：

1. --python 命令行参数
2. UV_PYTHON 环境变量
3. 当前项目的 .python-version 文件
4. pyproject.toml 中的 requires-python
5. 父目录的 .python-version 文件
6. 系统 PATH 中的 Python

项目管理

uv init

初始化新项目，创建 pyproject.toml 等基础文件。

uv init [OPTIONS] [PATH]

# 创建应用项目（默认）
uv init my-app
# 生成：pyproject.toml、README.md、.python-version、hello.py

# 创建库项目
uv init --lib my-library
# 生成：pyproject.toml、README.md、.python-version、src/my_library/__init__.py

# 创建可打包应用
uv init --package my-package

# 指定构建后端
uv init --lib --build-backend hatch my-library

# 最小化初始化（适合在已有目录中使用）
uv init --bare

# 在当前目录初始化（不创建子目录）
uv init

项目类型对比

应用项目（--app，默认）没有构建系统，不能用 uv build 打包，适合部署到服务器或容器。

库项目（--lib）有构建系统，可以用 uv build 生成 wheel，适合发布到 PyPI。

依赖管理

uv add

添加依赖到 pyproject.toml 并更新 uv.lock，同时安装到虚拟环境。

uv add [OPTIONS] <PACKAGES>...

# 添加生产依赖
uv add requests
uv add "fastapi>=0.100.0"
uv add "sqlalchemy[asyncio]>=2.0"

# 同时添加多个包
uv add requests httpx aiohttp

# 添加开发依赖
uv add --dev pytest ruff mypy

# 添加到指定依赖组
uv add --group lint ruff pyflakes
uv add --group test pytest pytest-asyncio coverage

# 添加可选依赖（extras）
uv add --optional network httpx aiohttp

# 本地可编辑包
uv add --editable ./packages/my-utils

# Git 依赖（URL 直接写在包名位置，--branch/--tag/--rev 控制引用）
uv add "git+https://github.com/user/repo"
uv add "git+https://github.com/user/repo" --branch main
uv add "git+https://github.com/user/repo" --tag v1.0.0
uv add "git+https://github.com/user/repo" --rev abc1234

# 平台特定依赖（通过环境标记）
uv add "pywinpty; sys_platform == 'win32'"
uv add "uvloop; sys_platform != 'win32'"

# 版本约束方式
uv add fastapi --bounds major    # >=0.115.5, <1
uv add fastapi --bounds minor    # >=0.115.5, <0.116
uv add fastapi --bounds exact    # ==0.115.5
uv add fastapi --bounds lower    # >=0.115.5（只设下界）

# 为脚本添加依赖（PEP 723）
uv add --script my_script.py requests rich

uv remove

移除依赖，更新 pyproject.toml 和 uv.lock。

uv remove [OPTIONS] <PACKAGES>...

uv remove requests
uv remove --dev pytest
uv remove --group lint ruff
uv remove --optional network httpx

依赖类型说明

uv 支持四种依赖类型，对应不同的使用场景：

依赖源（tool.uv.sources）

在 pyproject.toml 中配置非 PyPI 的依赖来源：

[tool.uv.sources]
# 本地路径（可编辑）
my-utils = { path = "./packages/my-utils", editable = true }

# 本地路径（不可编辑）
my-lib = { path = "../my-lib" }

# Git 仓库
my-git-pkg = { git = "https://github.com/user/repo", branch = "main" }
my-tagged-pkg = { git = "https://github.com/user/repo", tag = "v1.0.0" }
my-rev-pkg = { git = "https://github.com/user/repo", rev = "abc1234" }

# 工作区成员
shared-lib = { workspace = true }

# 指定索引
torch = { index = "pytorch" }

tool.uv.index
name = "pytorch"
url = "https://download.pytorch.org/whl/cpu"

锁定与同步

uv lock

创建或更新 uv.lock 锁定文件，解析所有依赖版本。

uv lock [OPTIONS]

# 生成/更新锁定文件
uv lock

# 升级所有依赖
uv lock --upgrade

# 升级单个包
uv lock --upgrade-package requests

# 升级到指定版本
uv lock --upgrade-package "requests==2.32.0"

# 验证锁定文件是否最新（CI 中常用，不写入）
uv lock --check

# 只查看变化，不写入
uv lock --dry-run

uv sync

将虚拟环境与 uv.lock 同步，使环境与锁定文件完全一致。

uv sync [OPTIONS]

# 标准同步（安装所有依赖含 dev）
uv sync

# 仅同步生产依赖（适合部署）
uv sync --no-dev

# 安装所有可选依赖
uv sync --all-extras

# 安装指定可选依赖
uv sync --extra docs --extra test

# CI 环境（不更新锁定文件）
uv sync --frozen

# 生产部署（要求锁定文件最新且不自动更新）
uv sync --locked --no-dev

# 精确同步（移除多余包，适合生产环境）
uv sync --exact --no-dev

# 安装依赖但不安装项目本身（Docker 分层优化）
uv sync --no-install-project

自动锁定与同步

uv run、uv sync、uv add、uv remove 都会自动执行锁定和同步，无需手动调用 uv lock。

可以通过以下方式控制自动行为：

# 禁止自动更新锁定文件（如锁定文件过期则报错）
uv run --locked python main.py

# 禁止检查锁定文件（直接使用，不验证是否最新）
uv run --frozen python main.py

运行命令

uv run

在项目虚拟环境中执行命令，自动完成环境同步。

uv run [OPTIONS] [COMMAND]

# 运行 Python 脚本
uv run python main.py
uv run main.py  # 也可以省略 python

# 运行项目中的工具
uv run pytest
uv run pytest tests/test_api.py -v
uv run ruff check .
uv run mypy src/

# 临时安装包运行（不污染项目依赖）
uv run --with rich python -c "import rich; rich.print('[bold]Hello[/bold]')"
uv run --with "httpx>=0.24" python fetch.py

# 使用 .env 文件
uv run --env-file .env python main.py

# 在工作区特定成员中运行
uv run --package api pytest tests/

# 带 frozen 标志（CI 环境，不更新锁定文件）
uv run --frozen pytest

脚本管理（PEP 723）

PEP 723 定义了在 Python 脚本中内联声明依赖的标准格式，uv 完整支持。

内联依赖声明

在脚本文件顶部添加元数据块：

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

import requests
from rich import print

response = requests.get("https://api.github.com")
print(response.json())

# 运行含内联依赖的脚本（uv 自动创建隔离环境并安装依赖）
uv run my_script.py

# 也可以显式指定
uv run --script my_script.py

为脚本添加/移除依赖

# 添加依赖到脚本（自动修改脚本文件的元数据块）
uv add --script my_script.py requests rich

# 移除脚本依赖
uv remove --script my_script.py requests

# 查看脚本依赖
uv run my_script.py --help

可执行脚本（Shebang）

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.12"
# dependencies = ["requests"]
# ///

import requests
print(requests.get("https://httpbin.org/get").status_code)

chmod +x my_script.py
./my_script.py  # 直接运行，uv 自动处理依赖

锁定脚本依赖

# 为脚本生成锁定文件（在脚本同目录创建 my_script.py.lock）
uv lock --script my_script.py

# 使用锁定文件运行（确保可重现）
uv run --locked my_script.py

工具管理

工具（tool）是安装到隔离环境并暴露可执行文件到 PATH 的命令行程序，不污染任何项目的依赖。

uvx（uv tool run）

临时运行工具，不永久安装。

uvx [OPTIONS] [COMMAND] [ARGS]...
# 等同于 uv tool run

# 临时运行工具
uvx ruff check .
uvx black --check .
uvx httpie GET https://httpbin.org/get

# 指定版本运行
uvx [email protected] check .
uvx --from "ruff==0.3.0" ruff check .
uvx --from "ruff>0.2.0,<0.4.0" ruff check .

# 带 extras 运行
uvx --from "mypy[faster-cache,reports]" mypy src/

# 带额外包运行（如 mkdocs 插件）
uvx --with mkdocs-material mkdocs serve

# 从 Git 运行
uvx --from "git+https://github.com/user/tool" tool-name

uv tool install

永久安装工具，添加到 PATH。

uv tool install [OPTIONS] <PACKAGE>

# 安装常用工具
uv tool install ruff
uv tool install mypy
uv tool install black
uv tool install cookiecutter
uv tool install httpie

# 安装特定版本
uv tool install "ruff==0.3.0"

# 安装带插件的工具
uv tool install mkdocs --with mkdocs-material --with mkdocs-minify-plugin

# 从 Git 安装
uv tool install "git+https://github.com/user/tool"

uv tool list

列出已安装的工具。

uv tool list [OPTIONS]

uv tool list
uv tool list --show-paths

uv tool upgrade

升级已安装的工具。

uv tool upgrade [OPTIONS] [NAMES]...

uv tool upgrade ruff
uv tool upgrade --all

uv tool uninstall

卸载工具。

uv tool uninstall [NAMES]...

uv tool uninstall ruff
uv tool uninstall --all

uv tool dir

查看工具安装目录。

uv tool dir  # 输出工具的 bin 目录路径

虚拟环境管理

uv venv

创建虚拟环境（pip 工作流使用，项目模式下 uv 自动管理 .venv）。

uv venv [OPTIONS] [PATH]

# 创建默认虚拟环境
uv venv

# 指定 Python 版本
uv venv --python 3.12
uv venv --python pypy3.10

# 指定路径
uv venv /path/to/myenv
uv venv .venv-py312

# 带 pip 的虚拟环境（传统工作流）
uv venv --seed

# 激活虚拟环境
source .venv/bin/activate      # Linux/macOS
.venv\Scripts\activate          # Windows CMD
.venv\Scripts\Activate.ps1      # Windows PowerShell

deactivate  # 退出

pip 兼容接口

uv 提供与 pip、pip-tools、virtualenv 兼容的命令接口，便于迁移。

uv pip install

uv pip install [OPTIONS] <PACKAGES>...

# 基本安装
uv pip install requests

# 从 requirements.txt 安装
uv pip install -r requirements.txt

# 可编辑安装
uv pip install -e .

# 指定索引
uv pip install --index-url https://pypi.org/simple/ requests

# 不使用缓存
uv pip install --no-cache requests

uv pip compile

将依赖声明编译为精确锁定的 requirements.txt。

uv pip compile [OPTIONS] <SRC_FILE>...

# 编译 requirements.in -> requirements.txt
uv pip compile requirements.in -o requirements.txt

# 从 pyproject.toml 编译（生产依赖）
uv pip compile pyproject.toml -o requirements.txt

# 含开发依赖
uv pip compile pyproject.toml --extra dev -o requirements-dev.txt

# 升级并重新编译
uv pip compile requirements.in --upgrade -o requirements.txt

# 带哈希值（安全部署）
uv pip compile requirements.in --generate-hashes -o requirements.txt

uv pip sync

将环境精确同步到 requirements.txt 中指定的包（会移除多余的包）。

uv pip sync [OPTIONS] <SRC_FILE>...

uv pip sync requirements.txt
uv pip sync requirements.txt requirements-dev.txt
uv pip sync --frozen requirements.txt  # 不验证哈希

uv pip list / show / check / tree

# 列出已安装的包
uv pip list
uv pip list --format json

# 显示包详情
uv pip show requests

# 检查依赖兼容性
uv pip check

# 显示依赖树
uv pip tree
uv pip tree --package requests  # 只显示指定包的依赖树

uv pip uninstall

uv pip uninstall requests
uv pip uninstall -r requirements.txt

构建与发布

uv build

构建源代码分发包（sdist）和二进制分发包（wheel）。

uv build [OPTIONS] [SRC]

# 构建 wheel 和 sdist
uv build

# 只构建 wheel
uv build --wheel

# 只构建 sdist
uv build --sdist

# 指定输出目录
uv build -o ./dist

# 为发布构建（不含本地 sources 配置）
uv build --no-sources

uv version

查看或修改项目版本号。

uv version [OPTIONS] [VALUE]

# 查看当前版本
uv version
uv version --short  # 只输出版本号

# 设置版本
uv version 1.2.3

# 自动递增
uv version --bump patch   # 1.0.0 -> 1.0.1
uv version --bump minor   # 1.0.0 -> 1.1.0
uv version --bump major   # 1.0.0 -> 2.0.0
uv version --bump alpha   # 1.0.0 -> 1.0.0a1
uv version --bump rc      # 1.0.0a1 -> 1.0.0rc1

# 预览变化
uv version --bump minor --dry-run

uv publish

将构建产物发布到 PyPI 或其他包索引。

uv publish [OPTIONS] [FILES]...

# 发布到 PyPI（需先配置 token）
uv publish --token pypi-xxxx

# 通过环境变量（推荐）
UV_PUBLISH_TOKEN=pypi-xxxx uv publish

# 发布到私有仓库
uv publish --publish-url https://my.private.repo/upload/

# 发布指定文件
uv publish dist/my_package-1.0.0-py3-none-any.whl

完整发布流程

# 1. 更新版本
uv version --bump minor

# 2. 构建（不含本地 sources）
uv build --no-sources

# 3. 验证构建产物（可选，使用 twine check）
uvx twine check dist/*

# 4. 发布
UV_PUBLISH_TOKEN=pypi-xxxx uv publish

# 5. 验证安装
uv run --with my-package --no-project python -c "import my_package; print(my_package.__version__)"

工作区（Workspaces）

工作区将多个相关 Python 包组织在同一仓库中，共享一个 uv.lock 文件，适合 monorepo 架构。

核心概念

• 工作区根：包含 [tool.uv.workspace] 的项目，也是一个工作区成员
• 工作区成员：工作区中的每个包，各自有独立的 pyproject.toml
• 共享锁定文件：所有成员共享根目录的 uv.lock，确保依赖一致性
• 共享虚拟环境：所有成员安装到同一个 .venv

工作区结构

my-workspace/
├── pyproject.toml          # 工作区根（含 [tool.uv.workspace]）
├── uv.lock                 # 所有成员共享的锁定文件
├── .venv/                  # 所有成员共享的虚拟环境
├── packages/
│   ├── core/
│   │   ├── pyproject.toml  # 工作区成员
│   │   └── src/core/
│   ├── api/
│   │   ├── pyproject.toml  # 工作区成员
│   │   └── src/api/
│   └── cli/
│       ├── pyproject.toml  # 工作区成员
│       └── src/cli/
└── apps/
    └── web/
        ├── pyproject.toml  # 工作区成员
        └── src/web/

配置工作区

工作区根的 pyproject.toml：

[project]
name = "my-workspace"
version = "0.1.0"
requires-python = ">=3.12"

[tool.uv.workspace]
members = ["packages/*", "apps/*"]
# exclude 用于排除匹配 members 的特定目录
exclude = ["packages/experimental"]

成员的 pyproject.toml：

[project]
name = "core"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = []

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

工作区成员间依赖

成员之间通过 tool.uv.sources 相互引用：

# packages/api/pyproject.toml
[project]
name = "api"
dependencies = ["core"]

[tool.uv.sources]
core = { workspace = true }

等同于可编辑安装，修改 core 的代码立即在 api 中生效，无需重新安装。

工作区命令

# 在工作区根执行：对所有成员操作
uv lock            # 为整个工作区解析依赖
uv sync            # 同步整个工作区的虚拟环境

# 针对特定成员
uv run --package api pytest tests/
uv sync --package core
uv add --package api fastapi

工作区限制

虚根（Virtual Workspace Root）

如果工作区根只是容器，不需要本身作为包，可以将其配置为虚包（不含 build-system）：

# 工作区根 pyproject.toml（虚根）
[project]
name = "my-workspace"
version = "0.1.0"
# 不含 [build-system]，是一个"非包"项目

[tool.uv.workspace]
members = ["packages/*"]

大型与复杂项目管理

单体仓库（Monorepo）最佳实践

推荐结构：

my-monorepo/
├── pyproject.toml          # 工作区根（虚根）
├── uv.lock
├── .python-version         # 统一 Python 版本
├── uv.toml                 # 全局 uv 配置
├── packages/
│   ├── shared/             # 共享工具库
│   ├── models/             # 数据模型
│   └── utils/              # 通用工具
├── services/
│   ├── api-service/        # FastAPI 服务
│   ├── worker-service/     # Celery Worker
│   └── admin-service/      # 管理后台
└── tools/
    └── scripts/            # 运维脚本

工作区根配置：

[project]
name = "my-monorepo"
version = "0.1.0"
requires-python = ">=3.12"

[tool.uv.workspace]
members = ["packages/*", "services/*", "tools/*"]

[tool.uv]
# 全局约束（覆盖所有成员的相同包版本）
constraint-dependencies = [
    "pydantic>=2.0",
]

依赖冲突解决

当成员之间有不兼容依赖时，通过 override-dependencies 强制统一：

# 工作区根 pyproject.toml
[tool.uv]
# 强制所有成员使用此版本（跳过成员自己的约束）
override-dependencies = [
    "numpy==1.26.4",
]

通过 constraint-dependencies 添加约束而不覆盖：

[tool.uv]
# 在成员约束基础上额外添加约束
constraint-dependencies = [
    "certifi>=2024.0",
]

依赖组嵌套（适合大型项目）

在复杂项目中，通过依赖组组合管理不同场景的依赖：

[dependency-groups]
# 基础开发工具
dev = ["ruff>=0.4", "mypy>=1.9"]

# 测试依赖
test = ["pytest>=8.0", "pytest-asyncio>=0.23", "coverage>=7.0"]

# 文档
docs = ["mkdocs>=1.5", "mkdocs-material>=9.0"]

# 完整开发环境（包含所有组）
full = [
    { include-group = "dev" },
    { include-group = "test" },
    { include-group = "docs" },
]

安装特定场景：

uv sync --group test                 # 只安装测试依赖
uv sync --group full                 # 安装完整开发环境
uv sync --no-dev --no-group docs     # 只安装生产依赖，排除 docs 组

条件依赖（平台/版本特定）

[project]
dependencies = [
    # Python 版本条件
    "tomllib; python_version < '3.11'",
    "importlib-metadata>=6.0; python_version < '3.12'",
    # 平台条件
    "pywin32>=306; sys_platform == 'win32'",
    "uvloop>=0.19; sys_platform != 'win32'",
    # CPU 架构条件
    "nvidia-cuda-runtime-cu12; platform_machine == 'x86_64' and sys_platform == 'linux'",
]

多 Python 版本测试

# 为不同 Python 版本创建独立的虚拟环境（临时）
uv run --python 3.10 pytest
uv run --python 3.11 pytest
uv run --python 3.12 pytest

# 结合 tox 或 nox 进行矩阵测试
# noxfile.py 中配置
# nox.options.sessions = ["test-3.10", "test-3.11", "test-3.12"]

路径依赖 vs 工作区

# 路径依赖（各自独立的锁定文件和环境）
[project]
dependencies = ["my-utils"]

[tool.uv.sources]
my-utils = { path = "../my-utils", editable = true }

包索引配置

配置私有/镜像索引

在 pyproject.toml 或 uv.toml 中配置：

tool.uv.index
name = "aliyun"
url = "https://mirrors.aliyun.com/pypi/simple/"

tool.uv.index
name = "tencent"
url = "https://mirrors.cloud.tencent.com/pypi/simple/"

# 私有仓库
tool.uv.index
name = "private"
url = "https://private.company.com/simple/"
# 设为默认索引（替换 PyPI）
default = true

索引优先级：命令行 --index > 配置文件中靠前的索引 > PyPI（默认）。

索引搜索策略

[tool.uv]
# first-index（默认）：找到包就停止，不继续搜索其他索引
index-strategy = "first-index"

# unsafe-first-match：选择第一个索引中找到的第一个兼容版本
index-strategy = "unsafe-first-match"

# unsafe-best-match：跨所有索引选择最佳版本
index-strategy = "unsafe-best-match"

将包固定到特定索引

防止依赖混淆攻击，将内部包固定到私有索引：

[tool.uv.sources]
my-internal-pkg = { index = "private" }

tool.uv.index
name = "private"
url = "https://private.company.com/simple/"
# 明确声明此包只能从 private 索引获取
explicit = true

索引认证

tool.uv.index
name = "private"
url = "https://private.company.com/simple/"

通过环境变量传递凭证（不要写入配置文件）：

# 用户名密码
export UV_INDEX_PRIVATE_USERNAME=myuser
export UV_INDEX_PRIVATE_PASSWORD=mypassword

# 或者 token（作为密码传入）
export UV_INDEX_PRIVATE_PASSWORD=mytoken

也可以在 URL 中嵌入（不推荐提交到版本控制）：

tool.uv.index
name = "private"
url = "https://${MY_USER}:${MY_TOKEN}@private.company.com/simple/"

缓存管理

缓存策略

uv 对不同来源的依赖使用不同缓存策略：

缓存是线程安全的、只追加的，支持多个 uv 进程并发使用同一缓存目录。

uv cache 命令

# 查看缓存占用大小
uv cache dir
du -sh $(uv cache dir)

# 清理所有缓存
uv cache clean

# 清理指定包的缓存
uv cache clean requests

# 删除未使用的缓存（精简）
uv cache prune

# CI 环境优化：删除预构建 wheel，保留从源码构建的 wheel
uv cache prune --ci

缓存强制刷新

# 重新验证所有包（忽略缓存）
uv sync --refresh

# 重新验证指定包
uv sync --refresh-package requests

# 完全不使用缓存
uv sync --no-cache

自定义缓存路径

# 通过环境变量
export UV_CACHE_DIR=/custom/cache/path

# 通过命令行
uv sync --cache-dir /custom/cache/path

自定义缓存键（动态依赖）

当项目依赖 C 扩展、Git 子模块或其他需要自定义缓存失效逻辑时：

[tool.uv]
cache-keys = [
    { file = "Cargo.toml" },          # Rust 扩展：Cargo.toml 变化时重建
    { file = "build.rs" },
    { git = true },                   # Git commit 变化时重建
    { env = "MY_BUILD_FLAG" },        # 环境变量变化时重建
]

配置文件

uv.toml vs pyproject.toml

uv.toml 中不能包含 [project]、[tool.uv.workspace]、[tool.uv.sources] 等项目相关字段，这些必须在 pyproject.toml 中。

常用配置项

# uv.toml 或 pyproject.toml 中的 [tool.uv]

[tool.uv]
# Python 版本
python-preference = "managed"   # 优先使用 uv 管理的 Python
python-downloads = "automatic"  # 自动下载缺失的 Python 版本
# 可选："manual"（手动下载）、"never"（不自动下载）

# 解析策略
resolution = "highest"          # 默认：选择最高兼容版本
# "lowest"：选择最低兼容版本（用于检查依赖下限）
# "lowest-direct"：直接依赖用最低，传递依赖用最高

# 链接模式（影响安装速度和磁盘使用）
link-mode = "clone"             # 默认：COW 克隆（支持的文件系统）
# "copy"：完整复制（兼容性最好，但最慢）
# "hardlink"：硬链接（快，但跨磁盘无效）
# "symlink"：符号链接

# 预发布处理
prerelease = "disallow"         # 默认：不使用预发布版本
# "allow"：允许预发布
# "if-necessary"：仅在无稳定版时使用

# 构建隔离
no-build-isolation = false      # 默认隔离构建环境

# 并发限制
concurrent-downloads = 50       # 并发下载数
concurrent-builds = 16          # 并发构建数
concurrent-installs = 8         # 并发安装数

配置项查找优先级

命令行参数 > 环境变量 > 项目 pyproject.toml [tool.uv] >
项目 uv.toml > 父目录 uv.toml > 用户 ~/.config/uv/uv.toml

环境变量参考

常用环境变量：

uv export

将 uv.lock 导出为其他格式（如 requirements.txt）。

uv export [OPTIONS]

# 导出生产依赖（含哈希，安全部署）
uv export --no-dev -o requirements.txt

# 导出所有依赖（含开发）
uv export -o requirements-dev.txt

# 不含哈希
uv export --no-dev --no-hashes -o requirements.txt

# 导出可选依赖
uv export --extra docs -o requirements-docs.txt

Docker 集成

基础 Dockerfile

FROM python:3.12-slim

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

# 设置工作目录
WORKDIR /app

# 先复制依赖声明文件（利用 Docker 层缓存）
COPY pyproject.toml uv.lock ./

# 安装依赖（不安装项目本身，充分利用层缓存）
RUN uv sync --frozen --no-install-project --no-dev

# 再复制项目代码
COPY . .

# 安装项目
RUN uv sync --frozen --no-dev

# 运行
CMD ["uv", "run", "python", "-m", "myapp"]

优化的多阶段 Dockerfile

FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim AS builder

WORKDIR /app

# 编译字节码（减少运行时启动时间）
ENV UV_COMPILE_BYTECODE=1
# 使用 copy 链接模式（容器跨文件系统）
ENV UV_LINK_MODE=copy

# 安装依赖（分层，利用 Docker 缓存）
RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=bind,source=uv.lock,target=uv.lock \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    uv sync --frozen --no-install-project --no-dev

# 复制代码并安装项目
COPY . .
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --frozen --no-dev

FROM python:3.12-slim AS runtime

WORKDIR /app

# 从 builder 复制虚拟环境
COPY --from=builder /app/.venv /app/.venv

# 复制项目代码
COPY --from=builder /app /app

# 将虚拟环境加入 PATH
ENV PATH="/app/.venv/bin:$PATH"

CMD ["python", "-m", "myapp"]

.dockerignore

.venv
.git
__pycache__
*.pyc
*.egg-info
dist/
.pytest_cache/
.mypy_cache/
.ruff_cache/

安全审计

# 扫描依赖的已知漏洞（查询 OSV 数据库）
uv audit

# 只审计指定依赖组
uv audit --only-group test

# 排除 dev 依赖
uv audit --no-dev

# 审计指定 PEP 723 脚本
uv audit --script my_script.py

# 不更新锁定文件（CI 中使用）
uv audit --frozen

最佳实践

新项目启动

# 1. 初始化项目
uv init --lib my-project    # 库
uv init --app my-app        # 应用
cd my-project

# 2. 指定 Python 版本
uv python pin 3.12

# 3. 添加依赖
uv add fastapi pydantic sqlalchemy
uv add --dev pytest ruff mypy

# 4. 运行
uv run python -m myapp
uv run pytest

CI/CD 配置

# GitHub Actions 示例
- name: Install uv
  uses: astral-sh/setup-uv@v5
  with:
    version: "latest"
    enable-cache: true

- name: Install dependencies
  run: uv sync --frozen --all-extras

- name: Run tests
  run: uv run pytest --cov

- name: Type check
  run: uv run mypy src/

- name: Lint
  run: uv run ruff check .

关键原则：

• CI 中始终使用 --frozen，确保使用锁定文件中的精确版本
• 使用 astral-sh/setup-uv action 可以自动利用 GitHub Actions 缓存
• uv.lock 必须提交到版本控制

生产部署

# 只安装生产依赖，精确同步
uv sync --frozen --no-dev --exact

# 或导出 requirements.txt 供部署使用
uv export --frozen --no-dev --no-hashes -o requirements.txt
pip install -r requirements.txt  # 在目标环境中

迁移现有 pip 项目

# 1. 初始化
uv init --bare  # 在已有项目目录

# 2. 从 requirements.txt 导入依赖
uv add $(cat requirements.txt | grep -v "^#" | tr "\n" " ")

# 或者保留 requirements.txt 格式
uv pip compile requirements.in -o requirements.txt

# 3. 验证
uv run python -c "import mymodule; print('OK')"

常见场景命令速查

踩坑与注意事项

1. uv.lock 不应手动编辑

uv.lock 是 uv 自动维护的文件，手动修改会导致解析状态不一致。需要修改依赖时，始终通过 uv add、uv remove、uv lock --upgrade-package 操作。

2. 工作区的 requires-python 取交集

工作区所有成员的 requires-python 取交集，如果某个成员要求 >=3.9，另一个要求 >=3.12，工作区的有效范围是 >=3.12。应在工作区根的 pyproject.toml 中声明最终的交集范围。

3. tool.uv.sources 不影响发布的包

[tool.uv.sources] 中的来源配置只在本地生效，发布到 PyPI 时会被忽略（这是预期行为）。发布前用 uv build --no-sources 构建以验证。

4. --frozen 和 --locked 的区别

• --frozen：完全不更新 uv.lock，直接用现有版本安装。即使 pyproject.toml 有变化也忽略。
• --locked：检查 uv.lock 是否与 pyproject.toml 一致，不一致则报错（不自动更新）。

CI 中推荐 --frozen，本地开发时如果不希望无意中更新锁定文件可用 --locked。

5. dev 依赖组 vs optional-dependencies

6. editable 安装的行为

工作区成员间依赖默认是可编辑的（editable）。路径依赖如果指定 editable = true，修改源码后无需重新安装即可生效。非可编辑的路径依赖修改后需要重新运行 uv sync。

7. Python 版本自动下载

默认情况下（python-downloads = "automatic"），uv 会在需要时自动下载 Python 版本。如果在离线环境或不希望自动下载，设置：

export UV_PYTHON_DOWNLOADS=never
# 或
uv sync --no-managed-python

8. 依赖解析失败排查

# 查看详细解析过程
uv lock --verbose

# 查看依赖树
uv pip tree

# 检查特定包的依赖原因
uv pip tree --package requests

# 尝试最低版本解析（检查下界是否正确）
uv lock --resolution lowest

最佳实践

始终提交 uv.lock：lock 文件保证团队和 CI 使用完全相同的依赖版本树。将其纳入版本控制，并在 PR 中一并更新。

使用 uv add 而非手动编辑 pyproject.toml：uv add 会同步更新 pyproject.toml 和 uv.lock，手动编辑后必须运行 uv lock 才能同步锁文件，容易遗漏。

# 正确
uv add httpx

# 错误：手动改 pyproject.toml 后忘记 uv lock，导致 lock 文件与声明不一致
# 手动编辑 pyproject.toml...
# uv sync  # lock 文件未更新，与 pyproject 不一致

在 [tool.uv] 中固定 Python 版本：避免不同环境使用不同 Python 版本导致行为差异。

[tool.uv]
python = "3.12"

CI 中使用 uv sync --frozen：--frozen 禁止 lock 文件更新，确保 CI 使用锁定版本，lock 文件若与 pyproject.toml 不一致则报错退出。

- name: Install deps
  run: uv sync --frozen

用 uvx 运行一次性工具，不污染项目依赖：对于 black、ruff、mypy 等仅在开发时使用的工具，用 uvx 直接运行而无需安装到项目虚拟环境。

uvx ruff check .
uvx black --check .

开发依赖用 uv add --dev：将测试、格式化、类型检查等工具声明为开发依赖，生产环境用 uv sync --no-dev 跳过安装。

uv add --dev pytest ruff mypy
# 生产部署
uv sync --no-dev

常见陷阱

陷阱：修改 pyproject.toml 后未重新生成 lock 文件

现象： uv sync 报错 "lock file is not consistent with pyproject.toml"，或安装的版本与 pyproject.toml 声明不符。

原因： 手动编辑 pyproject.toml 不会自动更新 uv.lock，两者产生不一致。

解决： 使用 uv add / uv remove 修改依赖，或修改后立即运行 uv lock。

# 修改 pyproject.toml 后必须执行
uv lock
uv sync

陷阱：缓存导致安装到旧版本

现象： 更新了版本约束，但 uv sync 后包版本未变化；或明明发布了新版本，uv 仍安装旧版本。

原因： uv 默认使用本地缓存（~/.cache/uv），缓存命中时不会重新下载。

解决： 清除缓存后重新同步。

uv cache clean
uv sync

陷阱：Workspace 中子包依赖解析冲突

现象： Workspace 根目录 uv lock 失败，提示某个子包要求的版本与其他子包冲突。

原因： Workspace 使用统一的 lock 文件，所有成员必须能共享同一个解析结果；子包之间的上界/下界约束互斥时无法解析。

解决： 放宽冲突包的版本约束，或在 [tool.uv] 中用 constraint-dependencies 固定中间版本。

# pyproject.toml (workspace root)
[tool.uv]
constraint-dependencies = ["pydantic>=2.0,<3"]

参见

• Python包管理工具
• FastAPI完全指南
• pytest完全指南
• Pydantic完全指南