uv 常用指令完整手册#

适用对象：使用 uv 管理 Python、虚拟环境、依赖、项目和命令行工具的开发者。先确认本机版本：uv --version。不同版本的可选参数可能略有变化；任何命令均可用 uv <命令> --help 查看本机准确语法。命令阅读方式：终端代码块内每条命令均在行尾以 # 写明用途、影响范围或使用注意事项；复制执行时可保留或删除该注释。

概念与安装#

uv 是 Astral 提供的 Python 包与项目管理工具。它可替代或整合 pip、pip-tools、virtualenv、pyenv 的部分工作：

文件/对象	作用
`pyproject.toml`	项目元数据、依赖和工具配置的声明文件
`uv.lock`	解析后的精确依赖版本，通常应提交到 Git
`.venv/`	项目默认虚拟环境，通常不提交到 Git
`uv.toml` 或 `pyproject.toml` 中的 `[tool.uv]`	uv 配置

安装与升级#

PowerShell：

1
winget install --id=astral-sh.uv -e
2
# 或使用官方安装脚本（请按官网当前说明执行）
3
irm https://astral.sh/uv/install.ps1 | iex
4

5
uv --version  # 查看当前安装的 uv 版本
6
uv self update  # 更新 uv 自身；包管理器安装时优先用包管理器更新

macOS/Linux 常见安装方式：

1
curl -LsSf https://astral.sh/uv/install.sh | sh
2
uv --version  # 查看当前安装的 uv 版本
3
uv self update  # 更新 uv 自身；包管理器安装时优先用包管理器更新

若通过 winget、Homebrew、pipx 或系统包管理器安装，请优先通过同一个包管理器升级。

全局帮助与诊断#

1
uv --help  # 显示 uv 的顶层命令和全局选项
2
uv help  # 查看指定主题或子命令的详细帮助
3
uv help add  # 查看指定主题或子命令的详细帮助
4
uv add --help  # 添加项目依赖，同时更新 pyproject.toml 与 uv.lock
5
uv --version  # 查看当前安装的 uv 版本

项目与依赖管理#

项目模式以 pyproject.toml 为中心。除非明确需要 pip 兼容工作流，新项目优先使用这些命令。

初始化项目：`uv init`#

1
uv init                         # 在当前目录初始化
2
uv init my-project              # 新建目录并初始化应用项目
3
uv init --lib my-library        # 库项目
4
uv init --package my-package    # 可构建/可安装的 Python 包
5
uv init --bare                  # 仅创建最小项目配置
6
uv init --python 3.12 my-app    # 指定目标 Python

常用初始化变体（命令末尾的目录名可替换）：

1
uv init --app my-app             # 创建应用项目，生成可直接运行的入口文件
2
uv init --lib my-library         # 创建库项目，适合被其他项目导入
3
uv init --package my-package     # 创建可构建、可安装和可发布的包项目
4
uv init --bare my-app            # 只创建最小 pyproject.toml，不生成示例代码
5
uv init --python 3.12 my-app     # 创建项目并要求使用 Python 3.12
6
uv init --no-workspace my-app    # 创建项目时不加入上级 uv 工作区（版本支持时）

参数说明：--app 面向应用程序，--lib 面向源码库，--package 适合需要构建发行包的项目；三者不要按习惯混用。初始化后应检查 pyproject.toml 中的 name、version、requires-python 和依赖组，再执行 uv sync。

初始化后重点检查 pyproject.toml 中的 requires-python，它定义项目支持的 Python 范围。

添加依赖：`uv add`#

1
uv add requests  # 添加项目依赖，同时更新 pyproject.toml 与 uv.lock
2
uv add "django>=5,<6"  # 添加项目依赖，同时更新 pyproject.toml 与 uv.lock
3
uv add requests rich  # 添加项目依赖，同时更新 pyproject.toml 与 uv.lock
4
uv add "git+https://github.com/encode/httpx"  # 添加项目依赖，同时更新 pyproject.toml 与 uv.lock
5
uv add "httpx @ git+https://github.com/encode/httpx"  # 添加项目依赖，同时更新 pyproject.toml 与 uv.lock
6
uv add -r requirements.in  # 添加项目依赖，同时更新 pyproject.toml 与 uv.lock

添加开发依赖或可选依赖：

1
uv add --dev pytest ruff  # 添加项目依赖，同时更新 pyproject.toml 与 uv.lock
2
uv add --group docs mkdocs  # 添加项目依赖，同时更新 pyproject.toml 与 uv.lock
3
uv add --optional server fastapi uvicorn  # 添加项目依赖，同时更新 pyproject.toml 与 uv.lock

常用来源：

1
uv add ../local-package                    # 本地路径
2
uv add --editable ../local-package         # 可编辑本地依赖
3
uv add "package @ https://host/pkg.whl"    # 直链 wheel

删除与升级依赖#

1
uv remove requests  # 移除声明的依赖，并更新锁文件和本地环境
2
uv remove --dev pytest  # 移除声明的依赖，并更新锁文件和本地环境
3
uv remove --group docs mkdocs  # 移除声明的依赖，并更新锁文件和本地环境
4

5
uv lock --upgrade                 # 尝试升级全部可升级依赖
6
uv lock --upgrade-package requests # 仅升级指定包
7
uv add "requests>=2.32"           # 修改约束并重锁定

uv remove 会修改声明、锁文件和环境；若只要重建环境，不应靠手动删包，应使用 uv sync。

解析、锁定、同步：`uv lock` 与 `uv sync`#

1
uv lock                  # 只生成/更新 uv.lock，不安装
2
uv sync                  # 让 .venv 与锁文件一致
3
uv sync --locked         # 禁止改动锁文件；适合 CI
4
uv sync --frozen         # 使用现有锁文件，不检查其是否最新
5
uv sync --no-dev         # 不安装 dev 依赖组
6
uv sync --group docs     # 包含指定依赖组
7
uv sync --all-groups     # 包含所有依赖组
8
uv sync --extra server   # 包含指定 extra
9
uv sync --all-extras     # 包含所有 extra
10
uv sync --no-install-project # 只装依赖，不安装当前项目

建议：本地开发用 uv sync；CI 中用 uv sync --locked，以便锁文件过期时立即失败。

查看依赖树：`uv tree`#

1
uv tree  # 显示锁定依赖的树状关系
2
uv tree --depth 2  # 限制显示的依赖层级，便于快速浏览
3
uv tree --package requests  # 只显示指定包相关的依赖子树
4
uv tree --invert --package urllib3  # 反向查看指定包被哪些依赖引入

正向树回答“某包依赖什么”，反向树回答“为什么安装了某包”。可用 uv tree --help 确认本机的筛选参数。

查看项目状态与版本#

1
uv run python --version  # 在项目受管理环境中执行命令，必要时自动同步依赖
2
uv version                    # 读取项目版本（项目已配置时）
3
uv version 1.2.0              # 设置版本
4
uv version --bump patch       # 递增补丁版本

运行命令与脚本#

在项目环境执行：`uv run`#

1
uv run python main.py  # 在项目受管理环境中执行命令，必要时自动同步依赖
2
uv run python -m http.server  # 在项目受管理环境中执行命令，必要时自动同步依赖
3
uv run pytest -q  # 在项目受管理环境中执行命令，必要时自动同步依赖
4
uv run ruff check .  # 在项目受管理环境中执行命令，必要时自动同步依赖
5
uv run -- python -c "import requests; print(requests.__version__)"  # 在项目受管理环境中执行命令，必要时自动同步依赖

uv run 会优先使用项目环境，并根据项目元数据确保依赖可用。它比先手动激活 .venv 更适合脚本、文档和 CI。

临时增加运行时依赖而不改项目文件：

1
uv run --with rich python -c "from rich import print; print('[green]OK[/green]')"  # 临时注入依赖运行命令，不写入项目文件
2
uv run --with "httpx>=0.27" python script.py  # 临时注入依赖运行命令，不写入项目文件

指定 Python：

1
uv run --python 3.12 python main.py  # 指定解释器运行命令；可能触发解释器查找或下载
2
uv run --python /path/to/python python main.py  # 指定解释器运行命令；可能触发解释器查找或下载

内联脚本元数据（单文件脚本）#

将依赖写在脚本头部，uv 可隔离地运行脚本：

1
# /// script
2
# requires-python = ">=3.11"
3
# dependencies = [
4
#   "httpx",
5
#   "rich",
6
# ]
7
# ///
8

9
import httpx
10
from rich import print
11

12
print(httpx.get("https://example.com").status_code)

1
uv run script.py  # 在项目受管理环境中执行命令，必要时自动同步依赖
2
uv add --script script.py httpx  # 把依赖写入单文件脚本的内联元数据
3
uv remove --script script.py httpx  # 从单文件脚本的内联元数据移除依赖

可用 uv init --script script.py 为已有脚本添加初始元数据（实际支持的选项以 uv init --help 为准）。

虚拟环境#

创建与使用：`uv venv`#

1
uv venv                         # 当前目录创建 .venv
2
uv venv .venv                   # 明确指定目录
3
uv venv --python 3.12           # 使用指定 Python
4
uv venv --seed                  # 安装基础打包工具（需要时才用）

激活方式：

1
.venv\Scripts\Activate.ps1      # PowerShell

1
source .venv/bin/activate       # macOS/Linux

但多数场景无需激活，直接用 uv run ... 或 uv pip ... 即可。退出已激活环境：deactivate。

指定环境目标#

1
uv pip install -p .venv requests  # 通过虚拟环境目录定位目标解释器并安装包
2
uv pip install --python .venv\Scripts\python.exe requests  # Windows 示例

VIRTUAL_ENV 可让 uv pip 感知已激活环境。使用项目命令时通常由 .venv 自动处理。

Python 版本管理#

uv 能发现、下载并选择 Python 解释器。下载行为和可用版本受操作系统、网络及 uv 版本影响。

查看与安装#

1
uv python list  # 列出可发现或已安装的 Python 解释器
2
uv python list --only-installed  # 列出可发现或已安装的 Python 解释器
3
uv python find  # 按版本约束查找可用 Python 解释器路径
4
uv python find 3.12  # 按版本约束查找可用 Python 解释器路径
5
uv python install 3.12  # 下载并安装指定 Python 版本供 uv 管理
6
uv python install 3.11 3.12  # 下载并安装指定 Python 版本供 uv 管理
7
uv python uninstall 3.11  # 移除由 uv 管理的指定 Python；勿移除系统 Python

固定项目 Python：`uv python pin`#

1
uv python pin 3.12  # 写入项目 Python 固定版本，通常更新 .python-version
2
uv python pin --resolved 3.12  # 写入项目 Python 固定版本，通常更新 .python-version

通常会写入 .python-version。将其提交到版本控制，可使团队和 CI 选择相同主次版本。

查找与使用规则#

解释器通常按如下来源选择：显式 --python、激活环境、.python-version、项目 requires-python、系统 Python/uv 管理的 Python。实际优先级可用：

1
uv python --help  # 查看 Python 管理子命令的当前版本帮助
2
uv python find --help  # 按版本约束查找可用 Python 解释器路径

pip 兼容接口#

当项目仍使用 requirements.txt、Docker 构建层或遗留脚本时，可用 uv pip 加速常见 pip 工作流。先创建环境：

1
uv venv  # 创建虚拟环境；未指定路径时默认使用当前目录 .venv

安装、卸载与查看#

1
uv pip install requests  # 使用 pip 兼容模式安装，不会更新项目锁文件
2
uv pip install -r requirements.txt  # 使用 pip 兼容模式安装，不会更新项目锁文件
3
uv pip install -e .  # 使用 pip 兼容模式安装，不会更新项目锁文件
4
uv pip uninstall requests  # 从目标环境卸载包，不会修改 pyproject.toml
5
uv pip list  # 列出目标环境已安装的包
6
uv pip show requests  # 显示包版本、路径和依赖元数据
7
uv pip freeze  # 以 requirements 格式输出当前环境包版本
8
uv pip tree  # 显示当前环境的安装依赖树
9
uv pip check  # 校验已安装包的依赖约束是否满足

编译和同步 requirements#

1
uv pip compile requirements.in -o requirements.txt  # 解析输入依赖并生成带精确版本的 requirements 文件
2
uv pip compile pyproject.toml -o requirements.txt  # 解析输入依赖并生成带精确版本的 requirements 文件
3
uv pip sync requirements.txt  # 严格同步 requirements；会卸载清单外的包

compile 生成带精确版本的清单；sync 将当前环境严格对齐清单，会移除清单外的包。执行 sync 前确认目标虚拟环境正确。

为多个 Python 版本编译：

1
uv pip compile --python-version 3.11 requirements.in -o requirements-py311.txt  # 解析输入依赖并生成带精确版本的 requirements 文件
2
uv pip compile --python-version 3.12 requirements.in -o requirements-py312.txt  # 解析输入依赖并生成带精确版本的 requirements 文件

与项目模式如何选择#

需求	推荐
新项目、团队协作、有 `pyproject.toml`	`uv add`、`uv lock`、`uv sync`
遗留 requirements 工作流	`uv pip compile`、`uv pip sync`
仅临时装一个包到指定环境	`uv pip install`

不要在同一项目里随意混用 uv add 和 uv pip install：后者不会更新 pyproject.toml 或 uv.lock，下次 uv sync 可能移除该包。

工具安装与运行#

“工具”是独立于项目的命令行程序，例如 ruff、black、pre-commit、cookiecutter。

一次性运行：`uvx` / `uv tool run`#

1
uvx ruff check .  # 临时下载并在隔离环境运行工具，不修改项目依赖
2
uvx --from httpie http https://example.com  # 临时下载并在隔离环境运行工具，不修改项目依赖
3
uv tool run black --check .  # 在隔离工具环境中运行命令，不污染项目环境
4
uv tool run --with ruff ruff check .  # 为临时工具环境额外注入依赖后运行

uvx 是 uv tool run 的常用简写，会使用隔离工具环境，适合不想长期安装的命令。

持久安装：`uv tool install`#

1
uv tool install ruff  # 持久安装命令行工具到 uv 工具目录
2
uv tool install pre-commit  # 持久安装命令行工具到 uv 工具目录
3
uv tool install --from git+https://github.com/psf/black black  # 从指定来源安装持久化命令行工具
4
uv tool list  # 列出已持久安装的命令行工具
5
uv tool upgrade ruff  # 尝试升级指定已安装工具
6
uv tool upgrade --all  # 尝试升级所有已安装工具
7
uv tool uninstall ruff  # 卸载持久化工具及其独立环境

若安装后提示命令找不到，请按终端提示把工具可执行目录加入 PATH；可用 uv tool dir 查看相关位置。

锁文件与导出#

导出 requirements：`uv export`#

1
uv export -o requirements.txt  # 从 uv.lock 导出其他系统可消费的依赖清单
2
uv export --format requirements-txt -o requirements.txt  # 从 uv.lock 导出其他系统可消费的依赖清单
3
uv export --no-dev -o requirements-prod.txt  # 从 uv.lock 导出其他系统可消费的依赖清单
4
uv export --group docs -o requirements-docs.txt  # 从 uv.lock 导出其他系统可消费的依赖清单
5
uv export --extra server -o requirements-server.txt  # 从 uv.lock 导出其他系统可消费的依赖清单

导出的文件用于不直接支持 uv.lock 的外部系统。导出后通常不要再手动修改；应修改 pyproject.toml 后重新导出。

构建与发布#

适用于已在 pyproject.toml 配置 build backend 的库/包项目。

1
uv build                    # 生成 dist/ 下的 sdist 和 wheel
2
uv build --wheel            # 只构建 wheel
3
uv build --sdist            # 只构建源码分发包
4
uv publish                  # 发布到默认索引
5
uv publish --repository-url https://test.pypi.org/legacy/  # 发布到指定兼容仓库地址；令牌应通过安全方式提供

发布前建议在干净环境验证安装：

1
uv venv /tmp/pkg-check  # 创建虚拟环境；未指定路径时默认使用当前目录 .venv
2
uv pip install --python /tmp/pkg-check/bin/python dist/*.whl  # 将包安装到明确指定的 Python 或虚拟环境

在 Windows 请将临时环境路径和 Python 路径替换为对应形式。令牌应通过环境变量、密钥管理或 uv 的认证功能提供，避免写入仓库。

工作区、可选依赖与依赖组#

依赖组（dependency groups）#

适合开发、文档、测试等“项目内部角色”依赖：

1
[dependency-groups]
2
dev = ["pytest>=8", "ruff>=0.6"]
3
docs = ["mkdocs-material>=9"]

1
uv add --dev pytest  # 添加项目依赖，同时更新 pyproject.toml 与 uv.lock
2
uv add --group docs mkdocs-material  # 添加项目依赖，同时更新 pyproject.toml 与 uv.lock
3
uv sync --group docs  # 同步指定依赖组，其他组按默认规则处理
4
uv sync --all-groups  # 同步所有依赖组，适合完整开发环境
5
uv run --group docs mkdocs build  # 在包含指定依赖组的项目环境中运行命令

dev 是最常见的开发组；同步生产环境时使用 --no-dev 或按团队策略明确选择所需组。

Extras（可选依赖）#

适合发布给使用者选择的功能集合：

1
[project.optional-dependencies]
2
server = ["fastapi>=0.110", "uvicorn>=0.29"]
3
postgres = ["psycopg[binary]>=3.1"]

1
uv add --optional server fastapi uvicorn  # 添加项目依赖，同时更新 pyproject.toml 与 uv.lock
2
uv sync --extra server  # 同步指定 optional extra 的依赖
3
uv sync --all-extras  # 同步全部 optional extras 的依赖

区分原则：开发工具用依赖组；库消费者可选择安装的能力用 extras。

工作区（workspace）#

多包仓库可在根 pyproject.toml 声明成员（具体字段以当前 uv 文档/帮助为准）：

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

常用操作：

1
uv lock  # 根据项目声明生成或刷新 uv.lock，不安装包
2
uv sync  # 让项目虚拟环境严格匹配 uv.lock
3
uv run --package api python -m api  # 在工作区中选择指定成员包的上下文运行

工作区内包互相依赖时，优先声明为 workspace/local source，而非发布后再从索引安装。此部分配置演进较快，落地前应核对 uv help 和当前官方文档。

缓存、配置与认证#

缓存：`uv cache`#

1
uv cache dir  # 显示 uv 缓存目录，便于检查空间或配置 CI 缓存
2
uv cache clean  # 删除全部或指定包缓存；之后可能需要重新下载
3
uv cache clean requests  # 删除全部或指定包缓存；之后可能需要重新下载
4
uv cache prune  # 清理不再需要的缓存条目以释放磁盘空间

clean 会删除缓存，后续安装需重新下载/构建；排查缓存异常或释放空间时使用。CI 中常用 uv cache prune --ci（若本机版本支持）清理不适合保存的缓存。

配置位置和常用选项#

项目配置可放在 uv.toml，或 pyproject.toml 的 [tool.uv]：

1
[tool.uv]
2
index-url = "https://pypi.org/simple"

一次性配置也可用命令行参数，例如：

1
uv add --index https://pypi.org/simple requests  # 添加项目依赖，同时更新 pyproject.toml 与 uv.lock
2
uv sync --offline  # 只使用本地缓存；缺少包或解释器时会失败
3
uv sync --no-index  # 禁止访问包索引；仅使用可用的本地或直连来源

私有源、索引优先级、受限构建、链接模式等会直接影响供应链和可复现性。团队应把非敏感项目配置提交入库；用户名、密码、令牌只放环境变量或凭据存储。

认证：`uv auth`#

新版本可使用 uv auth 管理索引凭据：

1
uv auth login <索引地址或主机>  # 为索引保存认证凭据；不要把令牌写进仓库
2
uv auth token <索引地址或主机>  # 显示或读取当前索引认证状态；注意终端输出泄露风险
3
uv auth logout <索引地址或主机>  # 移除指定索引的已保存认证凭据

该命令的可用性及参数取决于 uv 版本。对 CI，优先使用 CI 密钥机制注入短期令牌，避免交互式登录。

离线与网络排查#

1
uv sync --offline  # 只使用本地缓存；缺少包或解释器时会失败
2
uv pip install --offline -r requirements.txt  # 使用 pip 兼容模式安装，不会更新项目锁文件
3
uv cache dir  # 显示 uv 缓存目录，便于检查空间或配置 CI 缓存

离线模式仅能使用本地缓存中已有的 Python/包/构建产物。

命令总览#

1
uv init | add | remove | lock | sync | run | tree | export | version
2
uv venv  # 创建虚拟环境；未指定路径时默认使用当前目录 .venv
3
uv python list | find | install | pin | uninstall
4
uv pip install | uninstall | list | show | freeze | tree | check | compile | sync
5
uv tool run (uvx) | install | list | upgrade | uninstall | dir
6
uv build | publish
7
uv cache dir | clean | prune
8
uv auth login | token | logout
9
uv self update  # 更新 uv 自身；包管理器安装时优先用包管理器更新

最后，以本机帮助作为权威：uv <子命令> --help。当版本升级后，先阅读帮助中标记为 preview/experimental 的选项，再将其纳入团队脚本。

工作流#

最快上手#

新建应用项目#

1
uv init my-app  # 初始化项目结构和 pyproject.toml；会在新目录创建目录
2
cd my-app
3
uv add requests  # 添加项目依赖，同时更新 pyproject.toml 与 uv.lock
4
uv run python main.py  # 在项目受管理环境中执行命令，必要时自动同步依赖

上述操作会创建/更新 pyproject.toml、uv.lock 和 .venv。uv run 会在需要时自动同步环境。

接手已有项目#

1
git clone <仓库地址>
2
cd <项目目录>
3
uv sync  # 让项目虚拟环境严格匹配 uv.lock
4
uv run pytest  # 在项目受管理环境中执行命令，必要时自动同步依赖

只想临时运行一个包#

1
uvx ruff check .  # 临时下载并在隔离环境运行工具，不修改项目依赖
2
# 等价于
3
uv tool run ruff check .  # 在隔离工具环境中运行命令，不污染项目环境

CI 与 Docker#

CI 推荐模式#

1
uv sync --locked --no-dev  # 严格按现有锁文件同步；锁文件过期时失败，适合 CI
2
uv run pytest  # 在项目受管理环境中执行命令，必要时自动同步依赖

若 CI 已预装所需 Python，可让 uv 直接使用它；否则先执行 uv python install <版本>。缓存 .venv 时必须将 Python 版本、平台和锁文件变化纳入缓存键。

Docker 的基本思路#

先复制 pyproject.toml 与 uv.lock 并执行 uv sync --locked --no-install-project，提高依赖层缓存命中。
再复制源代码，执行 uv sync --locked。
运行时使用 .venv/bin/python（Linux）或 uv run。

生产镜像应使用 --no-dev，且不要把密钥、私有索引令牌或整个用户目录写进镜像层。

常见场景速查#

目标	命令
新建项目	`uv init my-app`
接手项目并装依赖	`uv sync`
新增生产依赖	`uv add requests`
新增开发依赖	`uv add --dev pytest`
删除依赖	`uv remove requests`
运行项目脚本	`uv run python main.py`
运行测试	`uv run pytest`
临时运行格式化工具	`uvx ruff check .`
安装长期使用的 CLI	`uv tool install ruff`
创建虚拟环境	`uv venv --python 3.12`
安装指定 Python	`uv python install 3.12`
固定项目 Python	`uv python pin 3.12`
查看依赖树	`uv tree`
升级锁定依赖	`uv lock --upgrade`
只升级一个包	`uv lock --upgrade-package requests`
生成 requirements	`uv export -o requirements.txt`
遗留项目严格同步	`uv pip sync requirements.txt`
CI 不允许改锁文件	`uv sync --locked`
构建 wheel/sdist	`uv build`
清理缓存	`uv cache clean`

故障排查#

`uv run` 或 `uv sync` 解析失败#

1
uv lock  # 根据项目声明生成或刷新 uv.lock，不安装包
2
uv tree  # 显示锁定依赖的树状关系
3
uv lock --upgrade-package <包名>  # 仅重新解析并尝试升级指定包及其必要依赖

检查相互冲突的版本范围、项目 requires-python、平台标记和私有索引可用性。不要通过随意删除 uv.lock 规避冲突；先确认冲突来源，再有意重建锁文件。

包“装了但 import 不到”#

确认命令使用了目标环境：

1
uv run python -c "import sys; print(sys.executable)"  # 在项目受管理环境中执行命令，必要时自动同步依赖
2
uv run python -m pip --version  # 在项目受管理环境中执行命令，必要时自动同步依赖

常见原因是系统 Python、已激活的旧环境与项目 .venv 混用。项目中优先使用 uv run，并避免裸用 python/pip。

`uv sync` 移除了手动安装的包#

这是正常的严格同步行为。将包加入项目声明：

1
uv add <包名>  # 添加项目依赖，同时更新 pyproject.toml 与 uv.lock

或者对遗留环境，维护该包在 requirements.txt 中，再运行 uv pip sync。

Python 版本不匹配#

1
uv python list  # 列出可发现或已安装的 Python 解释器
2
uv python install 3.12  # 下载并安装指定 Python 版本供 uv 管理
3
uv python pin 3.12  # 写入项目 Python 固定版本，通常更新 .python-version
4
uv sync --python 3.12  # 用指定 Python 解析并同步项目环境

同时检查 pyproject.toml 的 requires-python 是否允许该版本。

私有源下载失败#

按顺序检查：索引 URL、网络/VPN、证书代理、凭据、包名拼写和索引优先级。可使用详细输出帮助定位：

1
uv -v sync  # 以详细日志级别执行，便于初步排查
2
uv -vv sync  # 以最高常用详细级别执行，便于定位解析或网络问题

输出可能含有私有地址或包信息，提交日志前请先脱敏。

团队约定建议#

提交 pyproject.toml、uv.lock 和（需要统一 Python 时）.python-version。
忽略 .venv/、本地缓存、令牌和构建产物（除非发布流程要求保留）。
本地执行 uv sync；CI 执行 uv sync --locked。
项目依赖通过 uv add/uv remove 修改，避免手动改锁文件。
在 README 中以 uv run <命令> 写启动、测试和检查命令，减少环境差异。

わたしの部屋