跳转至

uv add

向项目添加依赖项。

依赖项将被添加到项目的 pyproject.toml 文件中。

如果某个依赖项已存在，它将更新为新的版本约束符，除非其标记（marker）与现有约束符不同，在这种情况下将为该依赖项添加另一个条目。

锁文件和项目环境将更新以反映已添加的依赖项。要跳过更新锁文件，请使用 --frozen。要跳过更新环境，请使用 --no-sync。

如果找不到任何请求的依赖项，uv 将退出并报错，除非提供了 --frozen 标志，在这种情况下 uv 将原样添加依赖项，而不检查它们是否存在或是否与项目兼容。

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

Usage

uv add [OPTIONS] <PACKAGES|--requirements <REQUIREMENTS>>

Arguments

PACKAGES

要添加的包，格式为 PEP 508 依赖项声明（例如 ruff==0.5.0）

Options

--active

优先使用激活的虚拟环境，而非项目的虚拟环境。

如果项目的虚拟环境已激活或没有虚拟环境处于激活状态，则此选项无效。

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

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

可以提供多次。

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

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

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

--bounds bounds

添加依赖项时使用的版本约束符类型。

当向项目添加依赖项时，如果未提供约束或 URL，则会根据该包的最新兼容版本添加约束。默认情况下，使用下限约束，例如 >=1.2.3。

当提供 --frozen 时，不执行解析，依赖项始终不带约束地添加。

此选项处于预览阶段，可能在未来的任何版本中发生变化。

可选值：

  • lower: 仅下限约束，例如 >=1.2.3
  • major: 允许相同的主版本，类似于 semver 的插入符（caret），例如 >=1.2.3, <2.0.0
  • minor: 允许相同的次版本，类似于 semver 的波浪号（tilde），例如 >=1.2.3, <1.3.0
  • exact: 锁定精确版本，例如 ==1.2.3
--branch branch

从 Git 添加依赖项时使用的分支

--cache-dir cache-dir

缓存目录路径。

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

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

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

--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 构建后端的设置，格式为 包名:键=值 对

--constraints, --constraint, -c constraints

使用给定的需求文件约束版本。

约束文件是类似于 requirements.txt 的文件，仅控制已安装需求的版本。约束不会添加到项目的 pyproject.toml 文件中，但会在依赖解析期间被遵守。

这等价于 pip 的 --constraint 选项。

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

--default-index default-index

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

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

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

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

--dev

将需求添加到开发依赖组 [env: UV_DEV=]

此选项是 --group dev 的别名。

--directory directory

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

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

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

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

--editable

以可编辑模式添加需求

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

为依赖项启用的额外功能（extras）。

可以多次提供。

要将此依赖项添加到可选 extra 而非主依赖中，请参见 --optional。

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

添加依赖项而不重新锁定项目 [env: UV_FROZEN=]

项目环境将不会同步。

--group group

将需求添加到指定的依赖组。

这些需求不会包含在项目的已发布元数据中。

--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 环境变量设置。

--keyring-provider keyring-provider

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

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

默认为 disabled。

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

可选值：

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

从 Git 添加依赖项时是否使用 Git LFS

--link-mode link-mode

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

默认情况下，在 macOS 和 Linux 上为 clone（也称为写时复制），在 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 版本的使用。

--marker, -m marker

将此标记（marker）应用于所有添加的包

--no-binary

不安装预构建的 wheel。

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

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

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

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

--no-build

不构建源代码分发。

启用后，解析过程不会运行任意 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-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=]

--no-sync

避免同步虚拟环境 [env: UV_NO_SYNC=]

--no-workspace

不要将依赖项添加为工作区成员。

默认情况下，当添加一个本地路径且位于工作区目录内的依赖项时，uv 会将其添加为工作区成员；传递 --no-workspace 可改为将包添加为直接路径依赖项。

--offline

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

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

--optional optional

将需求添加到包的指定 extra 的可选依赖项中。

然后可以在使用 --extra 标志安装项目时激活该组。

要为此需求启用可选 extra，请参见 --extra。

--package package

将依赖项添加到工作区中的特定包

--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 解释器。

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

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

--quiet, -q

使用静默输出。

重复此选项，例如 -qq，将启用静默模式，uv 不会向 stdout 写入任何输出。

--raw, --raw-sources

按原样添加依赖项。

默认情况下，uv 会使用 tool.uv.sources 部分来记录 Git、本地、可编辑和直接 URL 需求的源信息。当提供 --raw 时，uv 会将源需求添加到 project.dependencies 而不是 tool.uv.sources。

此外，默认情况下，uv 会为你的依赖项添加边界约束，例如 foo>=1.0.0。当提供 --raw 时，uv 将添加不带边界约束的依赖项。

--refresh

刷新所有缓存数据

--refresh-package refresh-package

刷新特定包的缓存数据

--reinstall, --force-reinstall

重新安装所有包，无论它们是否已安装。隐含 --refresh

--reinstall-package reinstall-package

重新安装特定包，无论它是否已安装。隐含 --refresh-package

--requirements, --requirement, -r requirements

添加给定文件中列出的包。

支持以下格式：requirements.txt、带内联元数据的 .py 文件、pylock.toml、pyproject.toml、setup.py 和 setup.cfg。

--resolution resolution

在给定包需求的不同兼容版本之间进行选择时使用的策略。

默认情况下，uv 将使用每个包的最新兼容版本（highest）。

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

可选值：

  • highest: 解析每个包的最高兼容版本
  • lowest: 解析每个包的最低兼容版本
  • lowest-direct: 解析任何直接依赖项的最低兼容版本，以及任何传递依赖项的最高兼容版本
--rev rev

从 Git 添加依赖项时使用的提交

--script script

将依赖项添加到指定的 Python 脚本，而不是添加到项目中。

如果提供，uv 将根据 PEP 723 将依赖项添加到脚本的内联元数据表中。如果不存在此类内联元数据表，将创建一个新的并添加到脚本中。通过 uv run 执行时，uv 将为脚本创建一个临时环境，并安装所有内联依赖项。

--system-certs

是否从平台的原生证书存储加载 TLS 证书 [env: UV_SYSTEM_CERTS=]

默认情况下，uv 使用捆绑的 Mozilla 根证书，这提高了可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，你可能希望使用平台的原生证书存储，特别是当你依赖系统证书存储中包含的企业信任根（例如，用于强制代理）时。

--tag tag

从 Git 添加依赖项时使用的标签

--upgrade, -U

允许包升级，忽略任何现有输出文件中的固定版本。隐含 --refresh

--upgrade-group upgrade-group

允许依赖组中所有包的升级，忽略任何现有输出文件中的固定版本

--upgrade-package, -P upgrade-package

允许特定包的升级，忽略任何现有输出文件中的固定版本。隐含 --refresh-package

--verbose, -v

使用详细输出。

你可以使用 RUST_LOG 环境变量配置细粒度日志记录。（https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives）

--workspace

将依赖项添加为工作区成员。

默认情况下，uv 会将位于工作区目录内的路径依赖项添加为工作区成员。当与路径依赖项一起使用时，该包将被添加到根 pyproject.toml 文件中的工作区 members 列表中。