uv sync

更新项目的环境。

同步操作确保所有项目依赖项已安装并与锁文件（lockfile）保持一致。

默认情况下，uv 会执行精确同步：移除那些未被声明为项目依赖项的包。使用 --inexact 标志可以保留多余的包。请注意，如果多余的包与项目依赖项冲突，它仍会被移除。此外，如果使用了 --no-build-isolation，uv 将不会移除多余的包，以避免移除可能的构建依赖项。

如果项目虚拟环境（.venv）不存在，它将被创建。

除非提供了 --locked 或 --frozen 标志，否则项目在同步之前会重新锁定。

uv 将在当前目录或任何父目录中搜索项目。如果找不到项目，uv 将退出并报错。

请注意，从锁文件安装时，uv 不会对已撤回（yanked）的包版本发出警告。

Usage

uv sync [OPTIONS]

Options

--active

将依赖项同步到激活的虚拟环境。

如果设置了 VIRTUAL_ENV 环境变量，uv 将优先使用激活的虚拟环境，而不是创建或更新项目或脚本的虚拟环境。

--all-extras

包含所有可选依赖项。

当 tool.uv.conflicts 中声明了两个或多个冲突的 extras 时，使用此标志将始终导致错误。

请注意，所有可选依赖项始终包含在解析中；此选项仅影响要安装的包的选择。

--all-groups

包含所有依赖组中的依赖项。

可以使用 --no-group 排除特定组。

--all-packages

同步工作区中的所有包。

工作区环境（.venv）将更新以包含所有工作区成员。

通过 --extra、--group 或相关选项指定的任何 extras 或组将应用于所有工作区成员。

--allow-insecure-host, --trusted-host allow-insecure-host

允许与主机建立不安全连接。

可以多次提供。

期望接收主机名（例如 localhost）、主机-端口对（例如 localhost:8080）或 URL（例如 https://localhost）。

警告：此列表中的主机将不会根据系统证书存储进行验证。仅在具有已验证来源的安全网络中使用 --allow-insecure-host，因为它会绕过 SSL 验证，可能使您遭受中间人攻击（MITM）。

也可以通过 UV_INSECURE_HOST 环境变量设置。

--cache-dir cache-dir

缓存目录路径。

默认情况下，在 macOS 和 Linux 上为 $XDG_CACHE_HOME/uv 或 $HOME/.cache/uv，在 Windows 上为 %LOCALAPPDATA%\uv\cache。

要查看缓存目录的位置，请运行 uv cache dir。

也可以通过 UV_CACHE_DIR 环境变量设置。

--check

检查 Python 环境是否与项目同步。

如果环境不是最新的，uv 将退出并报错。

--color color-choice

控制输出中颜色的使用。

默认情况下，uv 在写入终端时会自动检测颜色支持。

可选值：

auto: 仅当输出到支持颜色的终端或 TTY 时启用彩色输出
always: 无论检测到的环境如何，都启用彩色输出
never: 禁用彩色输出

--compile-bytecode, --compile

安装后将 Python 文件编译为字节码。

默认情况下，uv 不会将 Python（.py）文件编译为字节码（__pycache__/*.pyc）；而是在第一次导入模块时延迟编译。对于启动时间至关重要的使用场景，例如 CLI 应用程序和 Docker 容器，启用此选项可以用更长的安装时间换取更快的启动速度。

启用后，uv 会为了一致性处理整个 site-packages 目录（包括当前操作未修改的包）。与 pip 一样，它也会忽略错误。

也可以通过 UV_COMPILE_BYTECODE 环境变量设置。

--config-file config-file

用作配置的 uv.toml 文件路径。

虽然 uv 配置可以包含在 pyproject.toml 文件中，但在此上下文中不允许使用。

也可以通过 UV_CONFIG_FILE 环境变量设置。

--config-setting, --config-settings, -C config-setting

传递给 PEP 517 构建后端的设置，格式为 键=值 对

--config-settings-package, --config-settings-package config-settings-package

传递给特定包的 PEP 517 构建后端的设置，格式为 包名:键=值 对

--default-index default-index

默认包索引的 URL（默认为 https://pypi.org/simple）。

接受符合 PEP 503（简单仓库 API）的仓库，或按相同格式组织的本地目录。

此标志指定的索引优先级低于通过 --index 标志指定的所有其他索引。

也可以通过 UV_DEFAULT_INDEX 环境变量设置。

--directory directory

在运行命令之前切换到给定的目录。

相对路径以给定的目录为基准进行解析。

参见 --project 以仅更改项目根目录。

也可以通过 UV_WORKING_DIR 环境变量设置。

--dry-run

执行预演（dry run），不写入锁文件或修改项目环境。

在预演模式下，uv 将解析项目的依赖项并报告锁文件和项目环境的预期变更，但不会修改任何一方。

--exclude-newer exclude-newer

将候选包限制为在给定日期之前上传的版本。

日期是与每个分发作品的上传时间（即每个文件上传到包索引的时间）进行比较，而不是与包版本的发布日期进行比较。

接受 RFC 3339 时间戳（例如 2006-12-02T02:07:43Z）、相同格式的本地日期（例如 2006-12-02，基于系统配置的时区解析）、"友好"持续时间（例如 24 hours、1 week、30 days）或 ISO 8601 持续时间（例如 PT24H、P7D、P30D）。

持续时间不遵循本地时区的语义，始终以固定秒数解析，假设一天为 24 小时（例如，忽略夏令时转换）。不允许使用月和年等日历单位。

也可以通过 UV_EXCLUDE_NEWER 环境变量设置。

--exclude-newer-package exclude-newer-package

将特定包的候选版本限制为在给定日期之前上传的版本。

接受格式为 包名=日期 的包-日期对，其中 日期 是 RFC 3339 时间戳（例如 2006-12-02T02:07:43Z）、相同格式的本地日期（例如 2006-12-02，基于系统配置的时区解析）、"友好"持续时间（例如 24 hours、1 week、30 days）或 ISO 8601 持续时间（例如 PT24H、P7D、P30D）。

持续时间不遵循本地时区的语义，始终以固定秒数解析，假设一天为 24 小时（例如，忽略夏令时转换）。不允许使用月和年等日历单位。

可以为不同的包多次提供。

--extra extra

包含指定 extra 名称的可选依赖项。

可以多次提供。

当指定了多个 extras 或组且它们出现在 tool.uv.conflicts 中时，uv 将报告错误。

请注意，所有可选依赖项始终包含在解析中；此选项仅影响要安装的包的选择。

--extra-index-url extra-index-url

（已弃用：请改用 --index）除 --index-url 之外要使用的额外包索引 URL。

接受符合 PEP 503（简单仓库 API）的仓库，或按相同格式组织的本地目录。

通过此标志提供的所有索引优先级高于 --index-url（默认为 PyPI）指定的索引。当提供多个 --extra-index-url 标志时，较早的值优先级更高。

也可以通过 UV_EXTRA_INDEX_URL 环境变量设置。

--find-links, -f find-links

搜索候选分发作品的位置，作为注册表索引之外的补充来源。

如果是路径，目标必须是一个目录，顶层包含作为 wheel 文件（.whl）或源代码分发（例如 .tar.gz 或 .zip）的包。

如果是 URL，页面必须包含一个扁平列表，列出符合上述格式的包文件链接。

也可以通过 UV_FIND_LINKS 环境变量设置。

--fork-strategy fork-strategy

在跨 Python 版本和平台选择给定包的多个版本时使用的策略。

默认情况下，uv 会优化为每个受支持的 Python 版本（requires-python）选择每个包的最新版本，同时最小化跨平台的选定版本数量。

在 fewest 策略下，uv 会最小化每个包的选定版本数量，倾向于选择与更广泛的受支持 Python 版本或平台兼容的较旧版本。

也可以通过 UV_FORK_STRATEGY 环境变量设置。

可选值：

fewest: 优化为每个包选择最少数量的版本。如果较旧版本与更广泛的受支持 Python 版本或平台兼容，则可能优先选择它们
requires-python: 优化为每个受支持的 Python 版本选择每个包的最新支持版本

--frozen

同步而不更新 uv.lock 文件 [env: UV_FROZEN=]

不检查锁文件是否为最新，而是将锁文件中的版本作为唯一真实来源。如果锁文件缺失，uv 将退出并报错。如果 pyproject.toml 中包含尚未纳入锁文件的依赖项变更，这些变更将不会反映在环境中。

--group group

包含指定依赖组中的依赖项。

当指定了多个 extras 或组且它们出现在 tool.uv.conflicts 中时，uv 将报告错误。

可以多次提供。

--help, -h

显示此命令的简明帮助信息

--index index

解析依赖项时使用的 URL，作为默认索引的补充。

接受符合 PEP 503（简单仓库 API）的仓库，或按相同格式组织的本地目录。

通过此标志提供的所有索引优先级高于 --default-index（默认为 PyPI）指定的索引。当提供多个 --index 标志时，较早的值优先级更高。

不支持索引名称作为值。相对路径必须通过 ./ 或 ../（Unix）或 .\\、..\\、./ 或 ../（Windows）与索引名称区分开来。

也可以通过 UV_INDEX 环境变量设置。

--index-strategy index-strategy

在多个索引 URL 之间进行解析时使用的策略。

默认情况下，uv 会在第一个找到给定包的索引处停止，并将解析限制为该第一个索引上存在的包（first-index）。这可以防止"依赖混淆"攻击，即攻击者可以在备用索引上以相同名称上传恶意包。

也可以通过 UV_INDEX_STRATEGY 环境变量设置。

可选值：

first-index: 仅使用第一个返回给定包名匹配结果的索引
unsafe-first-match: 在所有索引中搜索每个包名，在移动到下一个索引之前穷尽第一个索引的版本
unsafe-best-match: 在所有索引中搜索每个包名，优先选择找到的"最佳"版本。如果一个包版本存在于多个索引中，则仅查看第一个索引的条目

--index-url, -i index-url

（已弃用：请改用 --default-index）Python 包索引的 URL（默认为 https://pypi.org/simple）。

接受符合 PEP 503（简单仓库 API）的仓库，或按相同格式组织的本地目录。

此标志指定的索引优先级低于通过 --extra-index-url 标志指定的所有其他索引。

也可以通过 UV_INDEX_URL 环境变量设置。

--inexact, --no-exact

不移除环境中存在的多余包。

启用后，uv 只会进行满足需求所需的最小变更。默认情况下，同步会从环境中移除任何多余的包

--keyring-provider keyring-provider

尝试使用 keyring 进行索引 URL 的身份验证。

目前仅支持 --keyring-provider subprocess，它将 uv 配置为使用 keyring CLI 处理身份验证。

默认值为 disabled。

也可以通过 UV_KEYRING_PROVIDER 环境变量设置。

可选值：

disabled: 不使用 keyring 进行凭据查找
subprocess: 使用 keyring 命令进行凭据查找

--link-mode link-mode

从全局缓存安装包时使用的方法。

在 macOS 和 Linux 上默认为 clone（也称为写时复制，Copy-on-Write），在 Windows 上默认为 hardlink。

警告：不建议使用 symlink 链接模式，因为它会在缓存和目标环境之间产生紧密耦合。例如，清除缓存（uv cache clean）将因移除底层源文件而破坏所有已安装的包。请谨慎使用符号链接。

也可以通过 UV_LINK_MODE 环境变量设置。

可选值：

clone: 从源克隆（即写时复制）包到目标位置
copy: 从源复制包到目标位置
hardlink: 从源硬链接包到目标位置
symlink: 从源符号链接包到目标位置

--locked

断言 uv.lock 将保持不变 [env: UV_LOCKED=]

要求锁文件是最新的。如果锁文件缺失或需要更新，uv 将退出并报错。

--managed-python

要求使用 uv 管理的 Python 版本 [env: UV_MANAGED_PYTHON=]

默认情况下，uv 倾向于使用它管理的 Python 版本。然而，如果没有安装 uv 管理的 Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

--no-binary

不安装预构建的 wheel。

给定的包将从源代码构建并安装。解析器仍会使用预构建的 wheel 提取包元数据（如果可用）。

也可以通过 UV_NO_BINARY 环境变量设置。

--no-binary-package no-binary-package

不安装特定包的预构建 wheel [env: UV_NO_BINARY_PACKAGE=]

--no-build

不构建源代码分发（source distributions）。

启用后，解析将不会运行任意 Python 代码。已构建的源代码分发的缓存 wheel 将被重用，但需要构建分发的操作将退出并报错。

也可以通过 UV_NO_BUILD 环境变量设置。

--no-build-isolation

构建源代码分发时禁用隔离。

假设 PEP 518 指定的构建依赖项已安装。

也可以通过 UV_NO_BUILD_ISOLATION 环境变量设置。

--no-build-isolation-package no-build-isolation-package

构建特定包的源代码分发时禁用隔离。

假设该包的 PEP 518 指定的构建依赖项已安装。

--no-build-package no-build-package

不构建特定包的源代码分发 [env: UV_NO_BUILD_PACKAGE=]

--no-cache, --no-cache-dir, -n

避免读取或写入缓存，在操作期间使用临时目录

也可以通过 UV_NO_CACHE 环境变量设置。

--no-config

避免发现配置文件（pyproject.toml、uv.toml）。

通常，配置文件会在当前目录、父目录或用户配置目录中被发现。

也可以通过 UV_NO_CONFIG 环境变量设置。

--no-default-groups

忽略默认依赖组。

默认情况下，uv 包含 tool.uv.default-groups 中定义的组。此选项禁用该行为，但仍可通过 --group 包含特定组。

也可以通过 UV_NO_DEFAULT_GROUPS 环境变量设置。

--no-dev

禁用开发依赖组 [env: UV_NO_DEV=]

此选项是 --no-group dev 的别名。参见 --no-default-groups 以禁用所有默认组。

--no-editable

将所有可编辑依赖项（包括项目和任何工作区成员）以非可编辑模式安装 [env: UV_NO_EDITABLE=]

--no-editable-package no-editable-package

将指定的可编辑包以非可编辑模式安装

--no-extra no-extra

在提供了 --all-extras 时，排除指定的可选依赖项。

可以多次提供。

--no-group no-group

禁用指定的依赖组 [env: UV_NO_GROUP=]

此选项始终优先于默认组、--all-groups 和 --group。

可以多次提供。

--no-index

忽略注册表索引（例如 PyPI），仅依赖直接 URL 依赖项和通过 --find-links 提供的依赖项

--no-install-local

不安装本地路径依赖项 [env: UV_NO_INSTALL_LOCAL=]

跳过当前项目、工作区成员和任何其他本地（路径或可编辑）包。仅安装远程/索引的依赖项。在 Docker 构建中很有用，可以先缓存大型第三方依赖项，然后单独分层安装本地包。

反向选项 --only-install-local 可用于仅安装本地包，排除所有远程依赖项。

--no-install-package no-install-package

不安装指定的包。

默认情况下，项目的所有依赖项都会安装到环境中。--no-install-package 选项允许排除特定包。请注意，这可能导致环境损坏，应谨慎使用。

反向选项 --only-install-package 可用于仅安装指定的包，排除所有其他包。

--no-install-project

不安装当前项目 [env: UV_NO_INSTALL_PROJECT=]

默认情况下，当前项目及其所有依赖项都会安装到环境中。--no-install-project 选项允许排除项目本身，但其所有依赖项仍会被安装。这在构建 Docker 镜像等场景中特别有用，将项目与其依赖项分开安装可以实现最佳的层缓存。

反向选项 --only-install-project 可用于仅安装项目本身，排除所有依赖项。

--no-install-workspace

不安装任何工作区成员，包括根项目 [env: UV_NO_INSTALL_WORKSPACE=]

默认情况下，所有工作区成员及其依赖项都会安装到环境中。--no-install-workspace 选项允许排除所有工作区成员，同时保留其依赖项。这在构建 Docker 镜像等场景中特别有用，将工作区与其依赖项分开安装可以实现最佳的层缓存。

反向选项 --only-install-workspace 可用于仅安装工作区成员，排除所有其他依赖项。

--no-managed-python

禁用 uv 管理的 Python 版本的使用 [env: UV_NO_MANAGED_PYTHON=]

相反，uv 将在系统上搜索合适的 Python 版本。

--no-progress

隐藏所有进度输出 [env: UV_NO_PROGRESS=]

例如，旋转动画或进度条。

--no-python-downloads

禁用 Python 的自动下载。

--no-sources

解析依赖项时忽略 tool.uv.sources 表。用于基于符合标准的、可发布的包元数据进行锁定，而不使用任何工作区、Git、URL 或本地路径源

也可以通过 UV_NO_SOURCES 环境变量设置。

--no-sources-package no-sources-package

不为指定包使用 tool.uv.sources 表中的源 [env: UV_NO_SOURCES_PACKAGE=]

--offline

禁用网络访问 [env: UV_OFFLINE=]

禁用后，uv 将仅使用本地缓存数据和本地可用文件。

--only-dev

仅包含开发依赖组。

项目及其依赖项将被省略。

此选项是 --only-group dev 的别名。隐含 --no-default-groups。

--only-group only-group

仅包含指定依赖组中的依赖项。

项目及其依赖项将被省略。

可以多次提供。隐含 --no-default-groups。

--output-format output-format

选择输出格式

[默认值: text]

可选值：

text: 以人类可读格式显示结果
json: 以 JSON 格式显示结果

--package package

为工作区中的特定包进行同步。

工作区环境（.venv）将更新以反映指定工作区成员包所声明的依赖项子集。

如果任何工作区成员不存在，uv 将退出并报错。

--prerelease prerelease

考虑预发布版本时使用的策略。

默认情况下，uv 会接受那些仅发布预发布版本的包，以及在其声明的版本说明符中包含显式预发布标记的第一方需求（if-necessary-or-explicit）。

也可以通过 UV_PRERELEASE 环境变量设置。

可选值：

disallow: 禁止所有预发布版本
allow: 允许所有预发布版本
if-necessary: 如果某个包的所有版本都是预发布版本，则允许预发布版本
explicit: 对于在其版本需求中带有显式预发布标记的第一方包，允许预发布版本
if-necessary-or-explicit: 如果某个包的所有版本都是预发布版本，或者该包在其版本需求中带有显式预发布标记，则允许预发布版本

--project project

在给定目录中发现项目。

所有 pyproject.toml、uv.toml 和 .python-version 文件将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境（.venv）也是如此。

其他命令行参数（如相对路径）将相对于当前工作目录解析。

参见 --directory 以完全更改工作目录。

在 uv pip 接口中使用时，此设置无效。

也可以通过 UV_PROJECT 环境变量设置。

--python, -p python

用于项目环境的 Python 解释器。

默认情况下，使用满足项目 requires-python 约束的第一个解释器。

如果提供了虚拟环境中的 Python 解释器，则不会将包同步到给定环境。该解释器将用于在项目中创建虚拟环境。

有关 Python 发现和支持的请求格式的详细信息，请参见 uv python。

也可以通过 UV_PYTHON 环境变量设置。

--python-platform python-platform

应安装需求的目标平台。

表示为"目标三元组"，一个描述目标平台的 CPU、供应商和操作系统名称的字符串，例如 x86_64-unknown-linux-gnu 或 aarch64-apple-darwin。

当目标为 macOS（Darwin）时，默认最低版本为 13.0。使用 MACOSX_DEPLOYMENT_TARGET 指定不同的最低版本，例如 14.0。

当目标为 iOS 时，默认最低版本为 13.0。使用 IPHONEOS_DEPLOYMENT_TARGET 指定不同的最低版本，例如 14.0。

当目标为 Android 时，默认最低 Android API 级别为 24。使用 ANDROID_API_LEVEL 指定不同的最低版本，例如 26。

警告：指定后，uv 将选择与目标平台兼容的 wheel；因此，安装的分发作品可能与当前平台不兼容。反之，从源代码构建的任何分发作品可能与目标平台不兼容，因为它们是为当前平台构建的。--python-platform 选项适用于高级使用场景。

可选值：

windows: x86_64-pc-windows-msvc 的别名，Windows 的默认目标
linux: x86_64-unknown-linux-gnu 的别名，Linux 的默认目标
macos: aarch64-apple-darwin 的别名，macOS 的默认目标
x86_64-pc-windows-msvc: 64 位 x86 Windows 目标
aarch64-pc-windows-msvc: ARM64 Windows 目标
i686-pc-windows-msvc: 32 位 x86 Windows 目标
x86_64-unknown-linux-gnu: x86 Linux 目标。相当于 x86_64-manylinux_2_28
aarch64-apple-darwin: 基于 ARM 的 macOS 目标，见于 Apple Silicon 设备
x86_64-apple-darwin: x86 macOS 目标
aarch64-unknown-linux-gnu: ARM64 Linux 目标。相当于 aarch64-manylinux_2_28
aarch64-unknown-linux-musl: ARM64 Linux 目标（musl）
x86_64-unknown-linux-musl: x86_64 Linux 目标（musl）
riscv64-unknown-linux: RISCV64 Linux 目标
x86_64-manylinux2014: manylinux2014 平台的 x86_64 目标。相当于 x86_64-manylinux_2_17
x86_64-manylinux_2_17: manylinux_2_17 平台的 x86_64 目标
x86_64-manylinux_2_28: manylinux_2_28 平台的 x86_64 目标
x86_64-manylinux_2_31: manylinux_2_31 平台的 x86_64 目标
x86_64-manylinux_2_32: manylinux_2_32 平台的 x86_64 目标
x86_64-manylinux_2_33: manylinux_2_33 平台的 x86_64 目标
x86_64-manylinux_2_34: manylinux_2_34 平台的 x86_64 目标
x86_64-manylinux_2_35: manylinux_2_35 平台的 x86_64 目标
x86_64-manylinux_2_36: manylinux_2_36 平台的 x86_64 目标
x86_64-manylinux_2_37: manylinux_2_37 平台的 x86_64 目标
x86_64-manylinux_2_38: manylinux_2_38 平台的 x86_64 目标
x86_64-manylinux_2_39: manylinux_2_39 平台的 x86_64 目标
x86_64-manylinux_2_40: manylinux_2_40 平台的 x86_64 目标
aarch64-manylinux2014: manylinux2014 平台的 ARM64 目标。相当于 aarch64-manylinux_2_17
aarch64-manylinux_2_17: manylinux_2_17 平台的 ARM64 目标
aarch64-manylinux_2_28: manylinux_2_28 平台的 ARM64 目标
aarch64-manylinux_2_31: manylinux_2_31 平台的 ARM64 目标
aarch64-manylinux_2_32: manylinux_2_32 平台的 ARM64 目标
aarch64-manylinux_2_33: manylinux_2_33 平台的 ARM64 目标
aarch64-manylinux_2_34: manylinux_2_34 平台的 ARM64 目标
aarch64-manylinux_2_35: manylinux_2_35 平台的 ARM64 目标
aarch64-manylinux_2_36: manylinux_2_36 平台的 ARM64 目标
aarch64-manylinux_2_37: manylinux_2_37 平台的 ARM64 目标
aarch64-manylinux_2_38: manylinux_2_38 平台的 ARM64 目标
aarch64-manylinux_2_39: manylinux_2_39 平台的 ARM64 目标
aarch64-manylinux_2_40: manylinux_2_40 平台的 ARM64 目标
aarch64-linux-android: ARM64 Android 目标
x86_64-linux-android: x86_64 Android 目标
wasm32-pyodide2024: 使用 Pyodide 2024 平台的 wasm32 目标。适用于 Python 3.12。参见 https://pyodide.org/en/stable/development/abi/312.html
wasm32-pyodide2025: 使用 Pyodide 2025 平台的 wasm32 目标。适用于 Python 3.13。参见 https://pyodide.org/en/stable/development/abi/313.html
arm64-apple-ios: iOS 设备的 ARM64 目标
arm64-apple-ios-simulator: iOS 模拟器的 ARM64 目标
x86_64-apple-ios-simulator: iOS 模拟器的 x86_64 目标

--quiet, -q