Article

包管理器 uv

更新于：2026-07-13

第一章：uv 简介与安装

1.1 uv 是什么？

概念名称	说明	注意事项
uv	由 Astral 开发的超高速 Python 包管理器和虚拟环境工具，使用 Rust 编写，兼容 pip 接口，旨在替代 pip、pip-tools 等传统工具	uv 不是一个完整的构建系统（如 Poetry），而是专注于依赖解析、安装和虚拟环境管理
核心功能	支持 venv 创建、pip 兼容命令（install/uninstall/list/freeze）、依赖锁定（lock）、同步（sync）等	所有命令默认使用本地缓存，极大提升重复操作速度
开源状态	开源（MIT 许可），托管于 GitHub（https://github.com/astral-sh/uv）	仍在快速迭代中，部分高级功能可能尚未稳定

1.2 uv 与 pip / pip-tools / Poetry / conda 的对比

工具名称	所属类别	主要用途	与 uv 的关键区别	注意事项
pip	官方包安装器	从 PyPI 安装 Python 包	单线程、无内置缓存优化、不支持 lock/sync	uv 完全兼容 pip 命令语法，可作为 drop-in 替代
pip-tools	依赖管理工具	通过 requirements.in 生成锁定的 requirements.txt	需额外步骤生成锁定文件，速度慢	uv 内置 lock 和 sync，无需 pip-compile/pip-sync
Poetry	项目管理与依赖工具	项目初始化、依赖管理、打包发布	使用 pyproject.toml 作为唯一配置，有独立 CLI	uv 不处理打包/发布，仅聚焦依赖解析与安装，可与 Poetry 互补
conda	跨语言环境管理器	管理 Python 及非 Python 依赖（如 C 库）	依赖解析基于自己的 solver，生态独立于 PyPI	uv 仅面向 PyPI 生态，不支持 conda channel，但可共存于同一系统

1.3 安装 uv

步骤名称	操作细节	注意事项
通过官方脚本安装（推荐）	在终端执行：`curl -LsSf https://astral.sh/uv/install.sh`	脚本会自动下载适配当前系统的二进制文件并添加到 PATH
通过包管理器安装	macOS: `brew install uv`；Windows: `winget install uv`；Linux（Debian/Ubuntu）: `apt install uv`	部分 Linux 发行版可能版本滞后，建议优先使用官方脚本
通过 pip 安装（不推荐）	`pip install uv`	此方式安装的是 Python 封装层，性能不如原生二进制，仅用于测试
手动下载二进制	从 GitHub Releases 页面下载对应平台的可执行文件（如 `uv-x86_64-linux.tar.gz`）	需手动解压并加入系统 PATH

1.4 验证安装与基本命令

方法名称	语法	用途	代码示例	注意事项
初始化	`uv init [project_name]`	初始化目录	`uv init`	生成最小的 pyproject.toml、uv.lock、.env 文件
查看版本	`uv --version`	验证 uv 是否成功安装并查看当前版本	`uv --version`	输出类似 “uv 0.5.0”
查看帮助	`uv --help`	列出所有可用子命令和选项	`uv --help`	显示 venv, pip, lock, sync 等主命令
创建虚拟环境	`uv venv`	在当前目录创建 .venv 虚拟环境	`uv venv`	默认使用系统 Python，可通过 `--python` 指定版本
安装包（测试）	`uv pip install requests`	测试包安装功能是否正常	`uv pip install requests`	首次运行会自动初始化缓存目录（`~/.cache/uv`）
列出已安装包	`uv pip list`	验证虚拟环境中包是否正确安装	`uv pip list`	需在激活虚拟环境后运行，或使用 `--python` 指定解释器路径

第二章：基础使用

2.1 创建虚拟环境（`uv venv`）

方法名称	语法	用途	代码示例	注意事项
uv venv	`uv venv [OPTIONS] [PATH]`	创建一个新的 Python 虚拟环境	`uv venv`	默认在当前目录创建名为 .venv 的虚拟环境
指定路径	`uv venv /path/to/venv`	在指定路径创建虚拟环境	`uv venv myproject_env`	路径可为相对或绝对路径
指定 Python 版本	`uv venv --python`	使用特定版本的 Python 解释器	`uv venv --python 3.11`	version 可为 3.11、python3.11、/usr/bin/python3.11 等
清除已有环境	`uv venv --clear`	若目标路径已存在虚拟环境，则先清除再重建	`uv venv --clear`	避免残留旧包导致冲突
不生成 pip	`uv venv --without-pip`	创建不包含 pip 的轻量虚拟环境	`uv venv --without-pip`	uv 自身可管理包，通常无需 pip，但某些工具可能依赖它

2.2 安装依赖包（`uv pip install`）

方法名称	语法	用途	代码示例	注意事项
安装单个包	`uv pip install`	从 PyPI 安装指定包及其依赖	`uv pip install requests`	自动解析并安装兼容版本
安装多个包	`uv pip install pkg1 pkg2`	一次性安装多个包	`uv pip install numpy pandas`	所有包在同一解析上下文中处理，避免版本冲突
从 requirements.txt 安装	`uv pip install -r requirements.txt`	按文件列表安装依赖	`uv pip install -r requirements.txt`	支持标准 pip 格式的 requirements 文件
指定索引源	`uv pip install --index-url`	使用自定义 PyPI 镜像	`uv pip install --index-url https://pypi.tuna.tsinghua.edu.cn/simple requests`	可配合 `--extra-index-url` 添加备用源
安装开发依赖	`uv pip install -e .`	以可编辑模式安装当前项目	`uv pip install -e .`	要求项目根目录存在 pyproject.toml 或 setup.py
强制重装	`uv pip install --force-reinstall`	忽略缓存，重新下载并安装	`uv pip install --force-reinstall requests`	用于修复损坏的安装
仅下载不安装	`uv pip install --download`	将包下载到指定目录	`uv pip install --download ./wheels requests`	适用于离线部署准备

2.3 卸载依赖包（`uv pip uninstall`）

方法名称	语法	用途	代码示例	注意事项
卸载单个包	`uv pip uninstall`	移除指定包	`uv pip uninstall requests`	不会自动卸载其依赖（除非 `--remove-dependencies`，但 uv 目前不支持该选项）
卸载多个包	`uv pip uninstall pkg1 pkg2`	一次性卸载多个包	`uv pip uninstall numpy pandas`	包名必须已安装，否则报错
静默卸载	`uv pip uninstall -y`	自动确认卸载，无需交互	`uv pip uninstall -y requests`	适用于脚本或 CI 环境
从文件卸载	`uv pip uninstall -r requirements.txt`	按文件列表卸载包	`uv pip uninstall -r to_remove.txt`	文件中每行一个包名，注释和选项会被忽略

⚠️ 注意：uv pip uninstall 不会自动移除孤立依赖（即未被其他包依赖的子依赖），需手动处理。

2.4 列出已安装包（`uv pip list`）

方法名称	语法	用途	代码示例	注意事项
列出所有包	`uv pip list`	显示当前环境中所有已安装包及版本	`uv pip list`	输出格式：Package Version
以 JSON 格式输出	`uv pip list --format json`	供程序解析的结构化输出	`uv pip list --format json`	返回 JSON 数组，含 name 和 version 字段
仅列出过时包	`uv pip list --outdated`	检查是否有新版本可用	`uv pip list --outdated`	需联网查询 PyPI
排除编辑安装包	`uv pip list --exclude-editable`	不显示以 `-e` 方式安装的包	`uv pip list --exclude-editable`	适用于检查第三方依赖
指定虚拟环境	`uv pip list --python`	查询非当前激活环境的包列表	`uv pip list --python ./myenv/bin/python`	无需激活虚拟环境即可检查

2.5 检查依赖关系（`uv pip check`）

方法名称	语法	用途	代码示例	注意事项
检查依赖冲突	`uv pip check`	验证已安装包之间是否存在版本冲突	`uv pip check`	若无冲突，输出为空；若有冲突，显示具体不兼容信息
指定 Python 环境	`uv pip check --python`	检查指定解释器环境中的依赖一致性	`uv pip check --python ./venv/bin/python`	适用于多环境项目
与安装命令结合	`uv pip install ... && uv pip check`	安装后立即验证依赖健康度	`uv pip install "django<4" && uv pip check`	推荐在 CI 中使用此组合确保稳定性

✅ 成功时无输出；❌ 失败时示例：

django 3.2.0 requires sqlparse>=0.2.2, but you have sqlparse 0.1.0 which is incompatible.

2.6 导出依赖列表（`uv pip freeze`）

方法名称	语法	用途	代码示例	注意事项
导出所有依赖	`uv pip freeze`	生成当前环境的精确依赖列表	`uv pip freeze > requirements.txt`	输出格式为 package==version，可用于复现环境
排除编辑安装包	`uv pip freeze --exclude-editable`	不包含 `-e` 安装的本地项目	`uv pip freeze --exclude-editable`	适合生成纯第三方依赖文件
指定环境导出	`uv pip freeze --python`	导出非当前环境的依赖	`uv pip freeze --python ./venv/bin/python`	无需激活虚拟环境
与 list 对比	`uv pip freeze` vs `uv pip list`	freeze 输出带 == 锁定版本，list 仅显示名称和版本	`uv pip freeze`	freeze 结果可直接用于 pip install -r，确保可重现性

📌 示例输出：

requests==2.31.0
urllib3==2.0.7

第三章：高级功能

3.1 使用 requirements.txt 安装依赖

方法名称	语法	用途	代码示例	注意事项
从 requirements.txt 安装	`uv pip install -r requirements.txt`	按文件中列出的包及其版本安装依赖	`uv pip install -r requirements.txt`	支持标准 pip 格式，包括注释（#）、空行、-e 等
多文件组合安装	`uv pip install -r req1.txt -r req2.txt`	同时处理多个依赖文件	`uv pip install -r base.txt -r dev.txt`	常用于分离生产/开发依赖
忽略已安装包	`uv pip install --no-deps -r requirements.txt`	仅安装顶层包，不安装其依赖	`uv pip install --no-deps -r requirements.txt`	极少使用，可能导致运行时错误
强制重新解析	`uv pip install --reinstall -r requirements.txt`	忽略缓存，重新解析并安装所有包	`uv pip install --reinstall -r requirements.txt`	用于解决缓存导致的版本不一致问题
静默模式	`uv pip install -q -r requirements.txt`	减少输出信息，适用于 CI/CD	`uv pip install -q -r requirements.txt`	-q 可多次使用（-qq）进一步降低日志级别

📌 requirements.txt 示例：

requests==2.31.0
# Development tools
pytest>=7.0
-e .

3.2 锁定依赖版本（`uv lock`）

方法名称	语法	用途	代码示例	注意事项
生成锁定文件	`uv lock`	基于 pyproject.toml 或 requirements.in 生成 uv.lock	`uv lock`	要求项目根目录存在 pyproject.toml（含 [project] 或 [tool.uv]）
指定 Python 版本锁定	`uv lock --python-version 3.11`	为特定 Python 版本生成兼容锁	`uv lock --python-version 3.11`	确保锁定结果与目标运行环境一致
强制更新锁	`uv lock --upgrade`	忽略现有 uv.lock，重新解析最新兼容版本	`uv lock --upgrade`	类似 poetry update 或 pip-tools —upgrade
仅升级指定包	`uv lock --upgrade-package`	更新单个包及其子依赖	`uv lock --upgrade-package requests`	可多次使用：`--upgrade-package A --upgrade-package B`
输出格式	自动生成 uv.lock	锁定文件为 TOML 格式，包含完整依赖图和哈希	（自动生成）	不建议手动编辑 uv.lock

⚠️ 注意：uv lock 目前主要面向 pyproject.toml 项目；若仅使用 requirements.txt，建议继续用 uv pip install -r。

3.3 同步依赖（`uv sync`）

方法名称	语法	用途	代码示例	注意事项
同步到锁定状态	`uv sync`	根据 uv.lock 安装/卸载包，使环境与锁文件一致	`uv sync`	自动创建 .venv（若不存在）并同步依赖
指定虚拟环境路径	`uv sync --venv path/to/venv`	将依赖同步到指定虚拟环境	`uv sync --venv ./myenv`	不影响全局 Python 环境
仅安装主依赖	`uv sync --no-dev`	忽略开发依赖（如 [project.optional-dependencies.dev]）	`uv sync --no-dev`	适用于生产环境部署
强制重建环境	`uv sync --reset`	清除现有虚拟环境并重新创建	`uv sync --reset`	解决环境污染或损坏问题
显示将执行的操作	`uv sync --dry-run`	预览将安装/卸载哪些包，不实际执行	`uv sync --dry-run`	用于安全验证变更

✅ 典型工作流：uv lock → uv sync

📌 uv sync 是可重现部署的核心命令，确保”所锁即所得”。

3.4 多 Python 版本支持

方法名称	语法	用途	代码示例	注意事项
指定解释器路径	`uv venv --python /path/to/python`	使用特定 Python 二进制创建环境	`uv venv --python /opt/python3.12/bin/python3`	路径需指向有效 Python 可执行文件
指定版本号	`uv venv --python 3.10`	自动查找系统中已安装的 Python 3.10	`uv venv --python 3.10`	依赖系统 PATH 或 pyenv 等版本管理器
在 lock 中指定	在 pyproject.toml 中设置 requires-python	控制依赖解析的 Python 兼容范围	`[project] requires-python = ">=3.9"`	`uv lock` 会据此排除不兼容包
查询可用 Python	`uv python list`	列出 uv 能识别的所有 Python 版本	`uv python list`	显示路径、版本、是否为虚拟环境等信息
安装新 Python（实验性）	`uv python install 3.12`	自动下载并安装 CPython（需启用）	`uv python install 3.12`	此功能仍在预览阶段，需确认是否启用

⚠️ uv 本身不打包 Python 解释器，多版本支持依赖系统已安装的 Python 或外部工具（如 pyenv、asdf）。

3.5 使用索引源（`--index-url` / `--extra-index-url`）

方法名称	语法	用途	代码示例	注意事项
指定主索引源	`uv pip install --index-url`	从自定义 PyPI 镜像安装包	`uv pip install --index-url https://pypi.tuna.tsinghua.edu.cn/simple requests`	替代默认 https://pypi.org/simple
添加备用索引	`uv pip install --extra-index-url`	当主源无包时，尝试备用源	`uv pip install --extra-index-url https://pypi.example.com/simple private-pkg`	可多次使用 `--extra-index-url`
全局配置索引	在 uv.toml 或 pyproject.toml 中配置	持久化设置索引源	`[tool.uv] index-url = "https://..."`	配置文件优先级：项目 > 用户 > 系统
安全连接	支持 HTTPS（默认）	所有索引请求默认加密	（自动启用）	不支持 insecure HTTP，除非显式允许（不推荐）
私有仓库认证	结合 netrc 或 token	访问需认证的私有 PyPI	`echo "machine pypi.example.com login token password pypi-xxx" > ~/.netrc`	uv 遵循标准 netrc 机制

📌 示例：国内加速

uv pip install --index-url https://mirrors.aliyun.com/pypi/simple/ django

3.6 离线安装与缓存管理

方法名称	语法	用途	代码示例	注意事项
查看缓存目录	`uv cache dir`	显示当前缓存路径（通常为 `~/.cache/uv`）	`uv cache dir`	缓存包含 wheel、metadata、git repos 等
清理缓存	`uv cache clean`	删除所有缓存数据	`uv cache clean`	可释放大量磁盘空间，但会降低后续安装速度
离线安装	`uv pip install --offline`	仅使用本地缓存安装，禁止网络请求	`uv pip install --offline requests`	要求所需包已存在于缓存中
预填充缓存	`uv pip download -d ./wheels -r requirements.txt`	提前下载所有依赖到本地目录	`uv pip download -d ./wheels -r prod.txt`	用于准备离线部署包
从本地目录安装	`uv pip install --find-links ./wheels -r requirements.txt`	从本地 wheel 目录安装	`uv pip install --find-links ./wheels -r requirements.txt`	`--find-links` 指向包含 .whl 或 sdist 的目录
禁用缓存	`uv pip install --no-cache-dir`	安装时不读写缓存	`uv pip install --no-cache-dir requests`	用于测试或避免缓存污染

✅ 离线工作流：

在联网机器：uv pip download -r reqs.txt -d ./offline
拷贝 ./offline 到目标机器
在目标机器：uv pip install --find-links ./offline --no-index -r reqs.txt

第四章：项目工作流集成

4.1 与 pyproject.toml 集成

概念/操作名称	说明	注意事项
pyproject.toml 支持	uv 原生读取项目根目录下的 pyproject.toml 文件，识别 `[project]` 和 `[tool.uv]` 配置段	要求符合 PEP 621 标准；若仅用于依赖管理，可不包含构建后端
依赖声明位置	在 `[project.dependencies]` 中列出主依赖，在 `[project.optional-dependencies]` 中定义额外依赖组（如 dev、test）	示例：`[project] dependencies = ["requests>=2.30"]` `[project.optional-dependencies] dev = ["pytest", "black"]`
Python 版本约束	通过 `[project.requires-python]` 指定兼容的 Python 版本范围	示例：`requires-python = ">=3.9,<3.13"`，`uv lock` 会据此过滤不兼容包
uv 专属配置	在 `[tool.uv]` 下设置索引源、构建选项等	示例：`[tool.uv] index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"`，这些配置对 uv 命令全局生效
可编辑安装项目	使用 `uv pip install -e .` 安装当前项目（需 pyproject.toml）	uv 会将项目以开发模式加入环境，并解析其 dependencies

📌 最小可运行 pyproject.toml 示例：

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

[project]
name = "myapp"
version = "0.1.0"
dependencies = ["click"]

4.2 替代 pip-tools 工作流

步骤名称	操作细节	注意事项
创建 requirements.in	手动编写高层依赖文件（如 `requests>=2.30`）	类似 pip-tools 的输入文件，但 uv 更推荐直接使用 pyproject.toml
生成锁定文件	使用 `uv lock` 代替 pip-compile	`uv lock` 生成 uv.lock（TOML 格式），而非 requirements.txt
同步环境	使用 `uv sync` 代替 pip-sync	`uv sync` 自动创建 .venv 并确保环境与 uv.lock 一致
更新依赖	使用 `uv lock --upgrade` 代替 `pip-compile --upgrade`	支持全量更新或指定包更新（`--upgrade-package`）
导出为 requirements.txt（可选）	若需兼容传统工具，可手动导出	uv 不直接输出 requirements.txt，但可通过 `uv pip freeze > requirements.txt` 间接实现

✅ 典型迁移路径：

原 pip-tools 流程：

pip-compile requirements.in → pip-sync requirements.txt

新 uv 流程：

uv lock → uv sync

优势：速度更快、依赖图更精确、无需维护多个 .txt 文件

4.3 在 CI/CD 中使用 uv

方法名称	语法	用途	代码示例	注意事项
安装 uv（CI 脚本）	`curl -LsSf https://astral.sh/uv/install.sh`	快速在 CI 环境部署 uv	`curl -LsSf https://astral.sh/uv/install.sh`	官方脚本支持 Linux/macOS/Windows
缓存 uv 缓存目录	缓存 `~/.cache/uv` 目录	加速重复构建	GitHub Actions 示例：`- uses: actions/cache@v4` `with: path: ~/.cache/uv` `key: uv-cache-${{ hashFiles('pyproject.toml') }}`	首次运行较慢，后续 job 极快
创建并同步环境	`uv sync --no-dev`	在 CI 中安装生产依赖	`uv sync --no-dev`	自动处理虚拟环境和依赖安装
运行测试	`source .venv/bin/activate && pytest`	激活环境并执行命令	（Linux/macOS）或直接使用 `.venv/bin/python -m pytest` 避免激活
静默输出	`uv sync -q`	减少日志噪音	`uv sync -q`	适用于日志敏感的 CI 系统
验证依赖健康	`uv pip check`	确保无版本冲突	`uv pip check`	建议在 install/sync 后立即运行

📌 推荐 CI 流程：

安装 uv
恢复缓存（~/.cache/uv）
uv sync --no-dev
uv pip check
运行测试/构建

4.4 与虚拟环境工具（如 virtualenv、venv）协同

操作名称	说明	注意事项
uv 自建虚拟环境	`uv venv` 默认创建 .venv，内部结构兼容标准 venv	可被任何 Python 工具识别（如 IDE、pip）
使用外部虚拟环境	`uv pip install --python /path/to/venv/bin/python pkg`	向已有 virtualenv/venv 环境安装包
与 virtualenv 共存	可先用 virtualenv 创建环境，再用 uv 管理包	示例：`virtualenv myenv` → `uv pip install --python myenv/bin/python requests`
与 python -m venv 共存	同样支持标准库 venv 创建的环境	uv 视所有符合 PEP 405 的环境为等效
激活方式不变	激活命令仍为 `source .venv/bin/activate`（Unix）或 `.venv\Scripts\activate`（Windows）	uv 不改变虚拟环境的使用习惯
环境隔离性	uv 的缓存（`~/.cache/uv`）是全局的，但安装行为严格限定于指定环境	多项目共享缓存提升速度，但环境彼此隔离

✅ 最佳实践：

日常开发：直接使用 uv venv + uv sync
遗留项目：用 uv pip install --python 指向现有 venv，逐步迁移

第五章：性能与原理

5.1 uv 的核心优势：Rust 编写、并行解析、缓存机制

概念名称	说明	注意事项
Rust 编写	uv 核心逻辑使用 Rust 语言实现，通过 PyO3 提供 Python CLI 接口	避免 CPython GIL 限制，内存安全且性能接近原生
并行依赖解析	在解析依赖图时，uv 并行请求 PyPI 元数据、并行下载 wheel	相比 pip 单线程，速度提升 10–100 倍（尤其在大型项目）
全局缓存机制	所有下载的 wheel、源码包、元数据均缓存在 `~/.cache/uv`	同一包在不同项目中复用，避免重复下载和构建
增量解析	仅当依赖声明变更时重新解析，否则直接复用已有解决方案	基于内容哈希（如 pyproject.toml 的 hash）判断是否需更新
内存高效	使用紧凑数据结构表示依赖图，减少内存占用	适合在资源受限环境（如 CI 容器）运行
零拷贝安装	安装 wheel 时直接链接或硬链接缓存文件，避免复制	显著加快安装速度，尤其对大型包（如 numpy、torch）

📌 性能对比示例（典型 Django 项目）：

pip install: ~30 秒
uv pip install: ~1.5 秒

5.2 依赖解析算法简介

概念名称	说明	注意事项
PubGrub 算法	uv 采用改进版 PubGrub（源自 Dart/Flutter），用于解决版本约束满足问题（CSP）	能高效处理复杂依赖冲突，并提供清晰的错误报告
回溯优化	当遇到冲突时，算法智能回溯并跳过无效版本组合	避免穷举所有可能，大幅减少搜索空间
预解析元数据缓存	在解析前预取所有候选包的 metadata（来自 PyPI JSON API）	减少网络往返，提升解析启动速度
兼容性优先级	优先选择高版本但兼容的包（而非最新版），确保稳定性	符合 PEP 440 版本规范和语义化版本约定
可重现性保障	解析结果由输入（依赖声明 + Python 版本）唯一确定	相同输入在不同机器上生成相同 uv.lock
支持可选依赖	正确处理 `[project.optional-dependencies]` 中的额外依赖组	开发依赖（dev）与主依赖隔离解析

⚠️ 注意：uv 不支持 pip 的 --prefer-binary 或 --force-reinstall 等非标准行为，因其破坏可重现性。

5.3 与 pip 的兼容性设计

兼容特性	说明	注意事项
命令行接口兼容	`uv pip install / list / freeze` 等命令语法与 pip 完全一致	可作为 drop-in 替代：`alias pip=uv pip`
requirements.txt 支持	完整支持标准 pip 格式的 requirements 文件（含 `-e`, `--index-url`, 注释等）	不支持 pip 的某些实验性选项（如 `--hash`，见 5.4）
虚拟环境兼容	创建的 .venv 符合 PEP 405，可被 pip、IDE、系统工具识别	`uv venv` 生成的结构与 `python -m venv` 一致
错误信息对齐	报错格式尽量模仿 pip，降低用户迁移成本	但冲突提示更清晰（得益于 PubGrub）
环境变量支持	支持 `PIP_INDEX_URL`、`PIP_EXTRA_INDEX_URL` 等标准环境变量	也可使用 `UV_INDEX_URL` 等 uv 专属变量
不兼容项	不支持 pip 的 `--user`、`--target`、`--prefix` 等全局安装选项	uv 强制使用虚拟环境，倡导隔离开发

✅ 推荐做法：在项目中使用 uv，但保留 pip 作为备用（如调试时）。

5.4 安全性与哈希校验

安全机制	说明	注意事项
HTTPS 强制启用	所有与 PyPI 或自定义索引的通信默认使用 TLS 加密	不允许 insecure HTTP，除非显式设置（不推荐）
Wheel 哈希校验	安装 wheel 时自动验证其 SHA256 哈希（若在 uv.lock 中记录）	uv.lock 包含每个包的 hash，确保内容未被篡改
来源完整性	从官方 PyPI 下载的包自动关联其发布签名（间接通过 CDN 完整性）	uv 本身不验证 PGP 签名（因 PyPI 不广泛使用）
不支持 `--require-hashes`	uv 不实现 pip 的 `--require-hashes` 模式	因 uv.lock 已提供更强的完整性保证，无需手动维护哈希
缓存隔离	缓存按 URL 和内容哈希隔离，防止恶意包污染	即使同一包名，不同来源或哈希会分别缓存
依赖来源追踪	uv.lock 记录每个包的原始下载 URL	便于审计和离线验证

📌 安全最佳实践：

始终提交 uv.lock 到版本控制
在 CI 中运行 uv pip check 验证依赖一致性
避免使用不可信的 --extra-index-url

第六章：故障排查与最佳实践

6.1 常见错误与解决方法

错误现象	可能原因	解决方法	注意事项
`error: No Python interpreter found`	系统未安装 Python 或 PATH 中不可见	安装 Python 并确保 `python3 --version` 可执行；或使用 `uv venv --python /full/path/to/python`	uv 不自带 Python 解释器，需系统预装
`error: Package not found`	包名拼写错误、私有包未配置索引源、或 PyPI 无此版本	检查包名；添加 `--index-url`；确认版本是否支持当前 Python	私有包需在 pyproject.toml 或命令行中指定额外索引
`error: Incompatible dependencies`	依赖之间存在版本冲突（如 A 要求 B<2，C 要求 B>=2）	运行 `uv pip check` 定位冲突；尝试放宽版本约束；或使用 `uv lock --upgrade-package` 单独更新某包	uv 的冲突提示比 pip 更清晰，注意阅读错误详情
`uv.lock not found`	执行 `uv sync` 前未运行 `uv lock`	先执行 `uv lock` 生成锁定文件	若项目仅用 requirements.txt，应改用 `uv pip install -r` 而非 `uv sync`
`Permission denied` 写入 .venv	在受限制目录（如系统目录）运行 `uv venv`	改在用户目录操作；或使用 sudo（不推荐）	推荐始终在项目根目录创建虚拟环境
缓存损坏导致安装失败	缓存文件意外中断或磁盘错误	运行 `uv cache clean` 清除缓存后重试	首次清理后安装会变慢，但可解决神秘错误

6.2 依赖冲突处理

操作名称	操作细节	注意事项
使用 `uv pip check` 诊断	在安装后运行，快速发现不兼容组合	输出示例：`packageA 1.0 requires packageB>=2.0, but you have packageB 1.5`
审查依赖来源	检查哪些顶层依赖引入了冲突子依赖	使用 pipdeptree（需临时安装）或手动分析 uv.lock
放宽版本约束	修改 pyproject.toml 中过于严格的版本（如将 `==` 改为 `>=`）	避免固定版本（`==`），除非必要
升级冲突包	使用 `uv lock --upgrade-package <conflicting-pkg>`	可能触发连锁升级，需验证功能
降级主依赖	若新版本引入不兼容，回退到旧版	示例：将 `django>=5.0` 改为 `django>=4.2,<5.0`
使用可选依赖隔离	将冲突工具放入不同 optional-dependencies 组	如 dev 和 test 分开，避免同时安装
手动编辑 uv.lock（不推荐）	仅在紧急调试时临时修改	下次 `uv lock` 会覆盖更改，应通过源头解决

✅ 原则：尽早锁定（lock）、频繁同步（sync）、持续检查（check）

6.3 推荐的项目结构

文件/目录	作用	最小可运行内容示例	说明
pyproject.toml	项目元数据与依赖声明	`[build-system] requires = ["hatchling"]` `build-backend = "hatchling.build"` `[project] name = "myapp"` `version = "0.1.0"` `dependencies = ["requests"]`	必须包含 `[project]` 段供 uv 读取依赖
uv.lock	依赖锁定文件（自动生成）	（由 `uv lock` 生成，TOML 格式）	应提交到 Git，确保团队环境一致
.venv/	虚拟环境目录（由 `uv venv` 创建）	（自动生成）	建议加入 .gitignore
.gitignore	忽略无需版本控制的文件	`.venv/` `__pycache__/` `*.pyc`	避免提交虚拟环境和缓存
README.md	项目说明	`# My Project` 含 uv 使用指引	提供 `uv sync` 和运行命令
tests/	测试代码目录	`tests/test_main.py`（含 assert）	可配合 `uv sync` 安装 dev 依赖后运行
scripts/（可选）	自定义脚本	`scripts/setup.sh: uv sync`	用于封装常用命令

📌 最佳实践：

所有开发者使用相同 uv.lock
CI 流程从 uv sync 开始，而非 pip install -r

6.4 性能调优建议

调优措施	操作方式	效果	注意事项
启用缓存复用	在 CI 中缓存 `~/.cache/uv`	减少 90%+ 的下载时间	缓存 key 应包含 pyproject.toml 哈希
使用 .venv 而非全局安装	始终通过 `uv venv` + `uv sync` 管理环境	避免环境污染，提升可重现性	不要混用 `pip install --user`
避免频繁 `uv lock`	仅在依赖变更时运行 `uv lock`	减少不必要的解析开销	日常开发用 `uv sync` 即可
使用国内镜像源	在 pyproject.toml 中配置 index-url	加速元数据和 wheel 下载	示例：`[tool.uv] index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"`
限制 Python 版本范围	明确设置 `requires-python = ">=3.9,<3.13"`	缩小依赖搜索空间，加快解析	避免过宽范围（如 `>=3.6`）
禁用开发依赖（生产环境）	使用 `uv sync --no-dev`	减少安装包数量，提升启动速度	确保生产镜像精简
使用 SSD 存储	将项目和缓存放于 SSD	加速文件 I/O（尤其 wheel 链接）	对大型项目效果显著

✅ 性能黄金法则：一次解析，处处同步；一次下载，处处复用。