CLI 参考

优先选择活动的虚拟环境，而不是项目的虚拟环境。

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

包括所有可选依赖项。

可选依赖项通过 pyproject.toml 中的 project.optional-dependencies 定义。

此选项仅在项目中运行时可用。

包括来自所有依赖组的依赖项。

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

--all-packages

在安装所有工作区成员的情况下运行命令。

工作区的环境 (.venv) 将被更新以包含所有工作区成员。

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

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

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

可以多次提供。

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

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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 环境变量设置。

--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 构建后端的设置，指定为 KEY=VALUE 对

--default-index default-index

默认包索引的 URL（默认情况下：https://pypi.ac.cn/simple）。

接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。

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

也可以使用 UV_DEFAULT_INDEX 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

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

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

--env-file env-file

从 .env 文件加载环境变量。

可以多次提供，后续文件覆盖先前文件中定义的值。

也可以使用 UV_ENV_FILE 环境变量设置。

--exact

执行精确同步，删除多余的包。

启用后，uv 将从环境中删除任何多余的包。默认情况下，uv run 将进行最小必要的更改以满足要求。

--exclude-newer exclude-newer

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

接受 RFC 3339 时间戳（例如，2006-12-02T02:07:43Z）和您系统配置时区中相同格式的本地日期（例如，2006-12-02）。

也可以使用 UV_EXCLUDE_NEWER 环境变量设置。

--extra extra

包括来自指定 extra 名称的可选依赖项。

可以多次提供。

可选依赖项通过 pyproject.toml 中的 project.optional-dependencies 定义。

此选项仅在项目中运行时可用。

--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 版本选择每个包的最新支持版本

在不更新 uv.lock 文件的情况下运行。

不检查锁定文件是否为最新，而是使用锁定文件中的版本作为真实来源。如果锁定文件丢失，uv 将退出并显示错误。如果 pyproject.toml 包含尚未包含在锁定文件中的依赖项更改，则它们将不会出现在环境中。

也可以使用 UV_FROZEN 环境变量设置。

--group group

包括来自指定依赖组的依赖项。

可以多次提供。

--gui-script

将给定路径作为 Python GUI 脚本运行。

使用 --gui-script 将尝试将路径解析为 PEP 723 脚本，并使用 pythonw.exe 运行它，而不管其扩展名如何。仅在 Windows 上可用。

--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.ac.cn/simple）。

接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。

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

也可以使用 UV_INDEX_URL 环境变量设置。

--isolated

在隔离的虚拟环境中运行命令。

通常，项目环境会为了性能而重用。此选项强制为项目使用新环境，从而强制依赖项和需求声明之间的严格隔离。

可编辑安装仍用于项目。

与 --with 或 --with-requirements 一起使用时，其他依赖项仍将在第二个环境中分层。

--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 上的 clone（也称为 Copy-on-Write），以及 Linux 和 Windows 上的 hardlink。

也可以使用 UV_LINK_MODE 环境变量设置。

可能的值

clone：将 wheel 中的包克隆（即，写时复制）到 site-packages 目录中
copy：将 wheel 中的包复制到 site-packages 目录中
hardlink：将 wheel 中的包硬链接到 site-packages 目录中
symlink：将 wheel 中的包符号链接到 site-packages 目录中

断言 uv.lock 将保持不变。

要求锁定文件是最新的。如果锁定文件丢失或需要更新，uv 将退出并显示错误。

也可以使用 UV_LOCKED 环境变量设置。

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

--module, -m

运行 Python 模块。

等同于 python -m <module>。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

不要安装预构建的 wheel 包。

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

也可以使用 UV_NO_BINARY 环境变量设置。

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

不要安装特定包的预构建 wheel 包

也可以使用 UV_NO_BINARY_PACKAGE 环境变量设置。

不要构建源分发包。

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

也可以使用 UV_NO_BUILD 环境变量设置。

构建源分发包时禁用隔离。

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

也可以使用 UV_NO_BUILD_ISOLATION 环境变量设置。

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

为特定包构建源分发包时禁用隔离。

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

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

不要构建特定包的源分发包

也可以使用 UV_NO_BUILD_PACKAGE 环境变量设置。

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

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

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

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

也可以使用 UV_NO_CONFIG 环境变量设置。

忽略默认依赖组。

uv 默认包含 tool.uv.default-groups 中定义的组。这将禁用该选项，但是仍然可以使用 --group 包含特定组。

禁用开发依赖组。

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

此选项仅在项目中运行时可用。

--no-editable

将任何可编辑依赖项（包括项目和任何工作区成员）安装为不可编辑

也可以使用 UV_NO_EDITABLE 环境变量设置。

--no-env-file

避免从 .env 文件读取环境变量

也可以使用 UV_NO_ENV_FILE 环境变量设置。

--no-extra no-extra

如果提供了 --all-extras，则排除指定的可选依赖项。

可以多次提供。

--no-group no-group

禁用指定的依赖组。

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

可以多次提供。

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

禁用 uv 管理的 Python 版本的使用。

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

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

--no-project, --no_workspace

避免发现项目或工作区。

不搜索当前目录和父目录中的项目，而是在由 --with 需求填充的隔离的临时环境中运行。

如果虚拟环境处于活动状态或在当前目录或父目录中找到，则将使用它，就好像没有项目或工作区一样。

禁用 Python 的自动下载。

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

避免同步虚拟环境。

暗示 --frozen，因为项目依赖项将被忽略（即，锁定文件将不会更新，因为无论如何都不会同步环境）。

也可以使用 UV_NO_SYNC 环境变量设置。

禁用网络访问。

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

也可以使用 UV_OFFLINE 环境变量设置。

仅包括开发依赖组。

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

此选项是 --only-group dev 的别名。暗示 --no-default-groups。

--only-group only-group

仅包括来自指定依赖组的依赖项。

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

可以多次提供。暗示 --no-default-groups。

--package package

在工作区中的特定包中运行命令。

如果工作区成员不存在，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 解释器。

如果发现的环境满足解释器请求，则将使用该环境。

请参阅 uv python 以查看支持的请求格式。

也可以使用 UV_PYTHON 环境变量设置。

--quiet, -q

使用安静输出。

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

刷新所有缓存数据

--refresh-package refresh-package

刷新特定包的缓存数据

--reinstall, --force-reinstall

重新安装所有包，无论它们是否已经安装。暗示 --refresh

--reinstall-package reinstall-package

重新安装特定包，无论它是否已经安装。暗示 --refresh-package

--resolution resolution

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

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

也可以使用 UV_RESOLUTION 环境变量设置。

可能的值

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

--script, -s

将给定路径作为 Python 脚本运行。

使用 --script 将尝试将路径解析为 PEP 723 脚本，而不管其扩展名如何。

--upgrade, -U

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

--upgrade-package, -P upgrade-package

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

--verbose, -v

使用详细输出。

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

--with, -w with

在安装给定包的情况下运行。

在项目中运行时，这些依赖项将以单独的临时环境分层在项目环境之上。这些依赖项可以与项目指定的依赖项冲突。

--with-editable with-editable

在可编辑模式下安装给定包的情况下运行。

在项目中运行时，这些依赖项将以单独的临时环境分层在项目环境之上。这些依赖项可以与项目指定的依赖项冲突。

--with-requirements with-requirements

在给定 requirements.txt 文件中列出的所有包的情况下运行。

与 --with 相同的环境语义适用。

不允许使用 pyproject.toml、setup.py 或 setup.cfg 文件。

uv init

创建一个新项目。

遵循 pyproject.toml 规范。

如果目标上已存在 pyproject.toml，uv 将退出并显示错误。

如果在目标路径的任何父目录中找到 pyproject.toml 文件，则该项目将被添加为父级的工作区成员。

某些项目状态在需要时才会创建，例如，项目虚拟环境 (.venv) 和锁定文件 (uv.lock) 在首次同步期间以延迟方式创建。

用法

uv init [OPTIONS] [PATH]

参数

PATH

用于项目/脚本的路径。

初始化应用程序或库时，默认为当前工作目录；初始化脚本时必需。接受相对路径和绝对路径。

如果在目标路径的任何父目录中找到 pyproject.toml 文件，则该项目将被添加为父级的工作区成员，除非提供了 --no-workspace。

Options (选项)

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

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

可以多次提供。

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

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

也可以使用 UV_INSECURE_HOST 环境变量设置。

--app, --application

为应用程序创建一个项目。

如果未请求 --lib，则这是默认行为。

此项目类型适用于 Web 服务器、脚本和命令行界面。

默认情况下，应用程序不打算作为 Python 包构建和分发。--package 选项可用于创建可分发的应用程序，例如，如果您想通过 PyPI 分发命令行界面。

--author-from author-from

在 pyproject.toml 中填写 authors 字段。

默认情况下，uv 将尝试从某些来源（例如 Git）推断作者信息 (auto)。使用 --author-from git 仅从 Git 配置中推断。使用 --author-from none 以避免推断作者信息。

可能的值

auto：自动从某些来源（例如 Git）获取作者信息
git：仅从 Git 配置中获取作者信息
none：不推断作者信息

--bare

仅创建 pyproject.toml。

禁用创建额外的文件，如 README.md、src/ 树、.python-version 文件等。

--build-backend build-backend

为项目初始化一个选择的构建后端。

隐式设置 --package。

可能的值

hatch：使用 hatchling 作为项目构建后端
flit：使用 flit-core 作为项目构建后端
pdm：使用 pdm-backend 作为项目构建后端
poetry：使用 poetry-core 作为项目构建后端
setuptools：使用 setuptools 作为项目构建后端
maturin：使用 maturin 作为项目构建后端
scikit：使用 scikit-build-core 作为项目构建后端

--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：禁用彩色输出

--config-file config-file

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

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

也可以使用 UV_CONFIG_FILE 环境变量设置。

--description description

设置项目描述

--directory directory

在运行命令之前更改为给定的目录。

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

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

--help, -h

显示此命令的简明帮助

--lib, --library

为库创建一个项目。

库是一个旨在作为 Python 包构建和分发的项目。

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

--name name

项目的名称。

默认为目录的名称。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

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

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

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

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

也可以使用 UV_NO_CONFIG 环境变量设置。

--no-description

禁用项目的描述

禁用 uv 管理的 Python 版本的使用。

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

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

--no-package

不要将项目设置为构建为 Python 包。

不包括项目的 [build-system]。

这是使用 --app 时的默认行为。

--no-pin-python

不要为项目创建 .python-version 文件。

默认情况下，uv 将创建一个 .python-version 文件，其中包含已发现的 Python 解释器的次要版本，这将导致后续 uv 命令使用该版本。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

--no-readme

不创建 README.md 文件

--no-workspace, --no-project

避免发现工作区并创建独立项目。

默认情况下，uv 会在当前目录或任何父目录中搜索工作区。

禁用网络访问。

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

也可以使用 UV_OFFLINE 环境变量设置。

--package

将项目设置为构建为 Python 包。

为项目定义一个 [build-system]。

这是使用 --lib 或 --build-backend 时的默认行为。

使用 --app 时，这将包括一个 [project.scripts] 入口点并使用 src/ 项目结构。

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

--script

创建一个脚本。

脚本是一个独立文件，其中包含嵌入式元数据，该元数据枚举了其依赖项以及 PEP 723 规范中定义的任何 Python 版本要求。

PEP 723 脚本可以直接使用 uv run 执行。

默认情况下，添加对系统 Python 版本的需求；使用 --python 指定备选 Python 版本要求。

--vcs vcs

为项目初始化一个版本控制系统。

默认情况下，uv 将初始化一个 Git 存储库 (git)。使用 --vcs none 以显式避免初始化版本控制系统。

可能的值

git：使用 Git 进行版本控制
none：不使用任何版本控制系统

--verbose, -v

使用详细输出。

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

uv add

将依赖项添加到项目中。

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

如果给定的依赖项已经存在，它将被更新为新的版本说明符，除非它包含与现有说明符不同的标记，在这种情况下，将添加该依赖项的另一个条目。

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

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

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

用法

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

参数

PACKAGES: 要添加的包，作为 PEP 508 要求（例如，ruff==0.5.0）

Options (选项)

优先选择活动的虚拟环境，而不是项目的虚拟环境。

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

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

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

可以多次提供。

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

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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 构建后端的设置，指定为 KEY=VALUE 对

--constraints, --constraint, -c constraints

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

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

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

也可以使用 UV_CONSTRAINT 环境变量进行设置。

--default-index default-index

默认包索引的 URL（默认情况下：https://pypi.ac.cn/simple）。

接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。

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

也可以使用 UV_DEFAULT_INDEX 环境变量设置。

--dev

将需求添加到开发依赖项组。

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

--directory directory

在运行命令之前更改为给定的目录。

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

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

--editable

以可编辑方式添加需求

--exclude-newer exclude-newer

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

接受 RFC 3339 时间戳（例如，2006-12-02T02:07:43Z）和您系统配置时区中相同格式的本地日期（例如，2006-12-02）。

也可以使用 UV_EXCLUDE_NEWER 环境变量设置。

--extra 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 版本选择每个包的最新支持版本

添加依赖项而不重新锁定项目。

项目环境将不会同步。

也可以使用 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.ac.cn/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 命令进行凭据查找

--link-mode link-mode

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

默认为 macOS 上的 clone（也称为 Copy-on-Write），以及 Linux 和 Windows 上的 hardlink。

也可以使用 UV_LINK_MODE 环境变量设置。

可能的值

clone：将 wheel 中的包克隆（即，写时复制）到 site-packages 目录中
copy：将 wheel 中的包复制到 site-packages 目录中
hardlink：将 wheel 中的包硬链接到 site-packages 目录中
symlink：将 wheel 中的包符号链接到 site-packages 目录中

断言 uv.lock 将保持不变。

要求锁定文件是最新的。如果锁定文件丢失或需要更新，uv 将退出并显示错误。

也可以使用 UV_LOCKED 环境变量设置。

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

--marker, -m marker

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

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

不要安装预构建的 wheel 包。

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

也可以使用 UV_NO_BINARY 环境变量设置。

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

不要安装特定包的预构建 wheel 包

也可以使用 UV_NO_BINARY_PACKAGE 环境变量设置。

不要构建源分发包。

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

也可以使用 UV_NO_BUILD 环境变量设置。

构建源分发包时禁用隔离。

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

也可以使用 UV_NO_BUILD_ISOLATION 环境变量设置。

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

为特定包构建源分发包时禁用隔离。

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

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

不要构建特定包的源分发包

也可以使用 UV_NO_BUILD_PACKAGE 环境变量设置。

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

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

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

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

也可以使用 UV_NO_CONFIG 环境变量设置。

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

禁用 uv 管理的 Python 版本的使用。

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

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

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

避免同步虚拟环境

也可以使用 UV_NO_SYNC 环境变量设置。

--no-workspace

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

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

禁用网络访问。

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

也可以使用 UV_OFFLINE 环境变量设置。

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

刷新特定包的缓存数据

--reinstall, --force-reinstall

重新安装所有包，无论它们是否已经安装。暗示 --refresh

--reinstall-package reinstall-package

重新安装特定包，无论它是否已经安装。暗示 --refresh-package

--requirements, --requirement, -r requirements

添加给定的 requirements.txt 文件中列出的所有包

--resolution resolution

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

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

也可以使用 UV_RESOLUTION 环境变量设置。

可能的值

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

--rev rev

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

--script script

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

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

--tag tag

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

--upgrade, -U

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

--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 列表中。

uv remove

从项目中删除依赖项。

依赖项将从项目的 pyproject.toml 文件中删除。

如果给定的依赖项存在多个条目，即每个条目都有不同的标记，则所有条目都将被删除。

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

如果请求的任何依赖项未出现在项目中，uv 将退出并显示错误。

如果一个包已在环境中手动安装，即使用 uv pip install，则它不会被 uv remove 删除。

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

用法

uv remove [OPTIONS] <PACKAGES>...

参数

PACKAGES: 要删除的依赖项的名称（例如，ruff）

Options (选项)

优先选择活动的虚拟环境，而不是项目的虚拟环境。

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

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

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

可以多次提供。

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

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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 环境变量设置。

--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 构建后端的设置，指定为 KEY=VALUE 对

--default-index default-index

默认包索引的 URL（默认情况下：https://pypi.ac.cn/simple）。

接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。

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

也可以使用 UV_DEFAULT_INDEX 环境变量设置。

--dev

从开发依赖项组中删除包。

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

--directory directory

在运行命令之前更改为给定的目录。

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

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

--exclude-newer exclude-newer

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

接受 RFC 3339 时间戳（例如，2006-12-02T02:07:43Z）和您系统配置时区中相同格式的本地日期（例如，2006-12-02）。

也可以使用 UV_EXCLUDE_NEWER 环境变量设置。

--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 版本选择每个包的最新支持版本

删除依赖项而不重新锁定项目。

项目环境将不会同步。

也可以使用 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.ac.cn/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 命令进行凭据查找

--link-mode link-mode

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

默认为 macOS 上的 clone（也称为 Copy-on-Write），以及 Linux 和 Windows 上的 hardlink。

也可以使用 UV_LINK_MODE 环境变量设置。

可能的值

clone：将 wheel 中的包克隆（即，写时复制）到 site-packages 目录中
copy：将 wheel 中的包复制到 site-packages 目录中
hardlink：将 wheel 中的包硬链接到 site-packages 目录中
symlink：将 wheel 中的包符号链接到 site-packages 目录中

断言 uv.lock 将保持不变。

要求锁定文件是最新的。如果锁定文件丢失或需要更新，uv 将退出并显示错误。

也可以使用 UV_LOCKED 环境变量设置。

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

不要安装预构建的 wheel 包。

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

也可以使用 UV_NO_BINARY 环境变量设置。

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

不要安装特定包的预构建 wheel 包

也可以使用 UV_NO_BINARY_PACKAGE 环境变量设置。

不要构建源分发包。

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

也可以使用 UV_NO_BUILD 环境变量设置。

构建源分发包时禁用隔离。

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

也可以使用 UV_NO_BUILD_ISOLATION 环境变量设置。

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

为特定包构建源分发包时禁用隔离。

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

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

不要构建特定包的源分发包

也可以使用 UV_NO_BUILD_PACKAGE 环境变量设置。

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

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

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

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

也可以使用 UV_NO_CONFIG 环境变量设置。

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

禁用 uv 管理的 Python 版本的使用。

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

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

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

在重新锁定项目后避免同步虚拟环境

也可以使用 UV_NO_SYNC 环境变量设置。

禁用网络访问。

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

也可以使用 UV_OFFLINE 环境变量设置。

--optional optional

从项目的指定 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。

刷新所有缓存数据

--refresh-package refresh-package

刷新特定包的缓存数据

--reinstall, --force-reinstall

重新安装所有包，无论它们是否已经安装。暗示 --refresh

--reinstall-package reinstall-package

重新安装特定包，无论它是否已经安装。暗示 --refresh-package

--resolution resolution

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

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

也可以使用 UV_RESOLUTION 环境变量设置。

可能的值

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

--script script

从指定的 Python 脚本中删除依赖项，而不是从项目中删除。

如果提供，uv 将从脚本的内联元数据表中删除依赖项，这符合 PEP 723。

--upgrade, -U

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

--upgrade-package, -P upgrade-package

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

--verbose, -v

使用详细输出。

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

uv version

读取或更新项目的版本

用法

uv version [OPTIONS] [VALUE]

参数

VALUE

将项目版本设置为此值

要使用语义版本控制组件更新项目，请改用 --bump。

Options (选项)

优先选择活动的虚拟环境，而不是项目的虚拟环境。

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

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

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

可以多次提供。

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

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

也可以使用 UV_INSECURE_HOST 环境变量设置。

--bump bump

使用给定的语义更新项目版本

可以多次传递此标志。

可能的值

major：增加主版本（例如，1.2.3 => 2.0.0）
minor：增加次版本（例如，1.2.3 => 1.3.0）
patch：增加补丁版本（例如，1.2.3 => 1.2.4）
stable：从预发行版本移动到稳定版本（例如，1.2.3b4.post5.dev6 => 1.2.3）
alpha：增加 alpha 版本（例如，1.2.3a4 => 1.2.3a5）
beta：增加 beta 版本（例如，1.2.3b4 => 1.2.3b5）
rc：增加 rc 版本（例如，1.2.3rc4 => 1.2.3rc5）
post：增加 post 版本（例如，1.2.3.post5 => 1.2.3.post6）
dev：增加 dev 版本（例如，1.2.3a4.dev6 => 1.2.3.dev7）

--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 构建后端的设置，指定为 KEY=VALUE 对

--default-index default-index

默认包索引的 URL（默认情况下：https://pypi.ac.cn/simple）。

接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。

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

也可以使用 UV_DEFAULT_INDEX 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

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

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

不要将新版本写入 pyproject.toml

相反，将显示该版本。

--exclude-newer exclude-newer

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

接受 RFC 3339 时间戳（例如，2006-12-02T02:07:43Z）和您系统配置时区中相同格式的本地日期（例如，2006-12-02）。

也可以使用 UV_EXCLUDE_NEWER 环境变量设置。

--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 版本选择每个包的最新支持版本

更新版本而不重新锁定项目。

项目环境将不会同步。

也可以使用 UV_FROZEN 环境变量设置。

--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.ac.cn/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 命令进行凭据查找

--link-mode link-mode

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

默认为 macOS 上的 clone（也称为 Copy-on-Write），以及 Linux 和 Windows 上的 hardlink。

也可以使用 UV_LINK_MODE 环境变量设置。

可能的值

clone：将 wheel 中的包克隆（即，写时复制）到 site-packages 目录中
copy：将 wheel 中的包复制到 site-packages 目录中
hardlink：将 wheel 中的包硬链接到 site-packages 目录中
symlink：将 wheel 中的包符号链接到 site-packages 目录中

断言 uv.lock 将保持不变。

要求锁定文件是最新的。如果锁定文件丢失或需要更新，uv 将退出并显示错误。

也可以使用 UV_LOCKED 环境变量设置。

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

不要安装预构建的 wheel 包。

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

也可以使用 UV_NO_BINARY 环境变量设置。

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

不要安装特定包的预构建 wheel 包

也可以使用 UV_NO_BINARY_PACKAGE 环境变量设置。

不要构建源分发包。

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

也可以使用 UV_NO_BUILD 环境变量设置。

构建源分发包时禁用隔离。

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

也可以使用 UV_NO_BUILD_ISOLATION 环境变量设置。

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

为特定包构建源分发包时禁用隔离。

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

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

不要构建特定包的源分发包

也可以使用 UV_NO_BUILD_PACKAGE 环境变量设置。

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

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

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

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

也可以使用 UV_NO_CONFIG 环境变量设置。

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

禁用 uv 管理的 Python 版本的使用。

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

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

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

在重新锁定项目后避免同步虚拟环境

也可以使用 UV_NO_SYNC 环境变量设置。

禁用网络访问。

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

也可以使用 UV_OFFLINE 环境变量设置。

--output-format output-format

输出的格式

[默认：文本]

可能的值

text：将版本显示为纯文本
json：将版本显示为 JSON

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

刷新所有缓存数据

--refresh-package refresh-package

刷新特定包的缓存数据

--reinstall, --force-reinstall

重新安装所有包，无论它们是否已经安装。暗示 --refresh

--reinstall-package reinstall-package

重新安装特定包，无论它是否已经安装。暗示 --refresh-package

--resolution resolution

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

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

也可以使用 UV_RESOLUTION 环境变量设置。

可能的值

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

--short

仅显示版本

默认情况下，uv 将在版本之前显示项目名称。

--upgrade, -U

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

--upgrade-package, -P upgrade-package

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

--verbose, -v

使用详细输出。

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

uv sync

更新项目的环境。

同步确保安装所有项目依赖项，并与锁定文件保持最新。

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

如果项目虚拟环境 (.venv) 不存在，则将创建它。

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

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

请注意，当从锁定文件安装时，uv 不会提供有关撤消的包版本的警告。

用法

uv sync [OPTIONS]

Options (选项)

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

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

包括所有可选依赖项。

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

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

包括来自所有依赖组的依赖项。

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

--all-packages

同步工作区中的所有包。

工作区的环境 (.venv) 将被更新以包含所有工作区成员。

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

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

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

可以多次提供。

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

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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 构建后端的设置，指定为 KEY=VALUE 对

--default-index default-index

默认包索引的 URL（默认情况下：https://pypi.ac.cn/simple）。

接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。

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

也可以使用 UV_DEFAULT_INDEX 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

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

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

执行模拟运行，而不写入锁定文件或修改项目环境。

在模拟运行模式下，uv 将解析项目的依赖项并报告对锁定文件和项目环境的最终更改，但不会修改任何一个。

--exclude-newer exclude-newer

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

接受 RFC 3339 时间戳（例如，2006-12-02T02:07:43Z）和您系统配置时区中相同格式的本地日期（例如，2006-12-02）。

也可以使用 UV_EXCLUDE_NEWER 环境变量设置。

--extra extra

包括来自指定 extra 名称的可选依赖项。

可以多次提供。

当指定出现在 tool.uv.conflicts 中的多个 extras 或组时，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 版本选择每个包的最新支持版本

同步而不更新 uv.lock 文件。

不检查锁定文件是否为最新，而是使用锁定文件中的版本作为真实来源。如果锁定文件丢失，uv 将退出并显示错误。如果 pyproject.toml 包含尚未包含在锁定文件中的依赖项更改，则它们将不会出现在环境中。

也可以使用 UV_FROZEN 环境变量设置。

--group group

包括来自指定依赖组的依赖项。

当指定出现在 tool.uv.conflicts 中的多个 extras 或组时，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.ac.cn/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 上的 clone（也称为 Copy-on-Write），以及 Linux 和 Windows 上的 hardlink。

也可以使用 UV_LINK_MODE 环境变量设置。

可能的值

clone：将 wheel 中的包克隆（即，写时复制）到 site-packages 目录中
copy：将 wheel 中的包复制到 site-packages 目录中
hardlink：将 wheel 中的包硬链接到 site-packages 目录中
symlink：将 wheel 中的包符号链接到 site-packages 目录中

断言 uv.lock 将保持不变。

要求锁定文件是最新的。如果锁定文件丢失或需要更新，uv 将退出并显示错误。

也可以使用 UV_LOCKED 环境变量设置。

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

不要安装预构建的 wheel 包。

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

也可以使用 UV_NO_BINARY 环境变量设置。

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

不要安装特定包的预构建 wheel 包

也可以使用 UV_NO_BINARY_PACKAGE 环境变量设置。

不要构建源分发包。

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

也可以使用 UV_NO_BUILD 环境变量设置。

构建源分发包时禁用隔离。

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

也可以使用 UV_NO_BUILD_ISOLATION 环境变量设置。

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

为特定包构建源分发包时禁用隔离。

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

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

不要构建特定包的源分发包

也可以使用 UV_NO_BUILD_PACKAGE 环境变量设置。

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

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

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

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

也可以使用 UV_NO_CONFIG 环境变量设置。

忽略默认依赖组。

uv 默认包含 tool.uv.default-groups 中定义的组。这将禁用该选项，但是仍然可以使用 --group 包含特定组。

禁用开发依赖组。

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

--no-editable

将任何可编辑依赖项（包括项目和任何工作区成员）安装为不可编辑

也可以使用 UV_NO_EDITABLE 环境变量设置。

--no-extra no-extra

如果提供了 --all-extras，则排除指定的可选依赖项。

可以多次提供。

--no-group no-group

禁用指定的依赖组。

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

可以多次提供。

--no-install-project

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

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

不要安装给定的包。

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

不要安装当前项目。

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

--no-install-workspace

不要安装任何工作区成员，包括根项目。

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

禁用 uv 管理的 Python 版本的使用。

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

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

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

禁用网络访问。

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

也可以使用 UV_OFFLINE 环境变量设置。

仅包括开发依赖组。

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

此选项是 --only-group dev 的别名。暗示 --no-default-groups。

--only-group only-group

仅包括来自指定依赖组的依赖项。

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

可以多次提供。暗示 --no-default-groups。

--output-format output-format

选择输出格式

[默认：文本]

可能的值

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) 为目标时，默认最低版本为 12.0。使用 MACOSX_DEPLOYMENT_TARGET 指定不同的最低版本，例如，13.0。

警告：指定后，uv 将选择与目标平台兼容的 wheels；因此，安装的发行版可能与当前平台不兼容。相反，任何从源代码构建的发行版可能与目标平台不兼容，因为它们将为当前平台构建。--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 目标
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 目标
x86_64-unknown-linux-musl：x86_64 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 目标
wasm32-pyodide2024：使用 Pyodide 2024 平台的 wasm32 目标。适用于 Python 3.12

--quiet, -q

使用安静输出。

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

刷新所有缓存数据

--refresh-package refresh-package

刷新特定包的缓存数据

--reinstall, --force-reinstall

重新安装所有包，无论它们是否已经安装。暗示 --refresh

--reinstall-package reinstall-package

重新安装特定包，无论它是否已经安装。暗示 --refresh-package

--resolution resolution

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

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

也可以使用 UV_RESOLUTION 环境变量设置。

可能的值

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

--script script

同步 Python 脚本的环境，而不是当前项目。

如果提供，uv 将根据脚本的内联元数据表同步依赖项，符合 PEP 723。

--upgrade, -U

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

--upgrade-package, -P upgrade-package

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

--verbose, -v

使用详细输出。

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

uv lock

更新项目的锁定文件。

如果项目锁定文件 (uv.lock) 不存在，则会创建它。如果存在锁定文件，其内容将用作解析的偏好设置。

如果项目的依赖项没有更改，则锁定将不起作用，除非提供 --upgrade 标志。

用法

uv lock [OPTIONS]

Options (选项)

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

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

可以多次提供。

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

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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, --locked

检查锁定文件是否为最新。

断言 uv.lock 在解析后将保持不变。如果缺少锁定文件或需要更新，uv 将以错误退出。

等效于 --locked。

也可以使用 UV_LOCKED 环境变量设置。

--check-exists, --frozen

断言 uv.lock 存在，而不检查它是否为最新。

等效于 --frozen。

也可以使用 UV_FROZEN 环境变量设置。

--color color-choice

控制输出中颜色的使用。

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

可能的值

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

--config-file config-file

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

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

也可以使用 UV_CONFIG_FILE 环境变量设置。

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

传递给 PEP 517 构建后端的设置，指定为 KEY=VALUE 对

--default-index default-index

默认包索引的 URL（默认情况下：https://pypi.ac.cn/simple）。

接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。

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

也可以使用 UV_DEFAULT_INDEX 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

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

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

执行模拟运行，而不写入锁定文件。

在模拟运行模式下，uv 将解析项目的依赖项并报告结果更改，但不会将锁定文件写入磁盘。

--exclude-newer exclude-newer

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

接受 RFC 3339 时间戳（例如，2006-12-02T02:07:43Z）和您系统配置时区中相同格式的本地日期（例如，2006-12-02）。

也可以使用 UV_EXCLUDE_NEWER 环境变量设置。

--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 版本选择每个包的最新支持版本

--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.ac.cn/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 命令进行凭据查找

--link-mode link-mode

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

此选项仅在构建源代码分发时使用。

默认为 macOS 上的 clone（也称为 Copy-on-Write），以及 Linux 和 Windows 上的 hardlink。

也可以使用 UV_LINK_MODE 环境变量设置。

可能的值

clone：将 wheel 中的包克隆（即，写时复制）到 site-packages 目录中
copy：将 wheel 中的包复制到 site-packages 目录中
hardlink：将 wheel 中的包硬链接到 site-packages 目录中
symlink：将 wheel 中的包符号链接到 site-packages 目录中

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

不要安装预构建的 wheel 包。

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

也可以使用 UV_NO_BINARY 环境变量设置。

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

不要安装特定包的预构建 wheel 包

也可以使用 UV_NO_BINARY_PACKAGE 环境变量设置。

不要构建源分发包。

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

也可以使用 UV_NO_BUILD 环境变量设置。

构建源分发包时禁用隔离。

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

也可以使用 UV_NO_BUILD_ISOLATION 环境变量设置。

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

为特定包构建源分发包时禁用隔离。

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

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

不要构建特定包的源分发包

也可以使用 UV_NO_BUILD_PACKAGE 环境变量设置。

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

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

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

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

也可以使用 UV_NO_CONFIG 环境变量设置。

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

禁用 uv 管理的 Python 版本的使用。

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

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

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

禁用网络访问。

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

也可以使用 UV_OFFLINE 环境变量设置。

--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 解释器，以确定没有 wheels 时的软件包元数据。

如果未设置 requires-python，则解释器也用作最低 Python 版本的后备值。

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

也可以使用 UV_PYTHON 环境变量设置。

--quiet, -q

使用安静输出。

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

刷新所有缓存数据

--refresh-package refresh-package

刷新特定包的缓存数据

--resolution resolution

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

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

也可以使用 UV_RESOLUTION 环境变量设置。

可能的值

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

--script script

锁定指定的 Python 脚本，而不是当前项目。

如果提供，uv 将锁定脚本（基于其内联元数据表，符合 PEP 723）到脚本本身旁边的 .lock 文件。

--upgrade, -U

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

--upgrade-package, -P upgrade-package

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

--verbose, -v

使用详细输出。

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

uv export

将项目的锁定文件导出为备用格式。

目前，支持 requirements.txt 和 pylock.toml (PEP 751) 格式。

除非提供 --locked 或 --frozen 标志，否则在导出之前重新锁定项目。

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

如果在工作区中操作，则默认情况下将导出根目录；但是，可以使用 --package 选项选择特定的成员。

用法

uv export [OPTIONS]

Options (选项)

包括所有可选依赖项

包括来自所有依赖组的依赖项。

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

--all-packages

导出整个工作区。

所有工作区成员的依赖项都将包含在导出的 requirements 文件中。

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

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

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

可以多次提供。

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

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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 环境变量设置。

--color color-choice

控制输出中颜色的使用。

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

可能的值

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

--config-file config-file

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

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

也可以使用 UV_CONFIG_FILE 环境变量设置。

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

传递给 PEP 517 构建后端的设置，指定为 KEY=VALUE 对

--default-index default-index

默认包索引的 URL（默认情况下：https://pypi.ac.cn/simple）。

接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。

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

也可以使用 UV_DEFAULT_INDEX 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

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

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

--exclude-newer exclude-newer

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

接受 RFC 3339 时间戳（例如，2006-12-02T02:07:43Z）和您系统配置时区中相同格式的本地日期（例如，2006-12-02）。

也可以使用 UV_EXCLUDE_NEWER 环境变量设置。

--extra extra

包括来自指定 extra 名称的可选依赖项。

可以多次提供。

--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 版本选择每个包的最新支持版本

--format format

导出 uv.lock 的格式。

支持 requirements.txt 和 pylock.toml (PEP 751) 输出格式。

如果提供，uv 将从输出文件的文件扩展名推断输出格式。否则，默认为 requirements.txt。

可能的值

requirements.txt：以 requirements.txt 格式导出
pylock.toml：以 pylock.toml 格式导出

在导出之前，请勿更新 uv.lock。

如果 uv.lock 不存在，uv 将以错误退出。

也可以使用 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.ac.cn/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 命令进行凭据查找

--link-mode link-mode

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

此选项仅在构建源代码分发时使用。

默认为 macOS 上的 clone（也称为 Copy-on-Write），以及 Linux 和 Windows 上的 hardlink。

也可以使用 UV_LINK_MODE 环境变量设置。

可能的值

clone：将 wheel 中的包克隆（即，写时复制）到 site-packages 目录中
copy：将 wheel 中的包复制到 site-packages 目录中
hardlink：将 wheel 中的包硬链接到 site-packages 目录中
symlink：将 wheel 中的包符号链接到 site-packages 目录中

断言 uv.lock 将保持不变。

要求锁定文件是最新的。如果锁定文件丢失或需要更新，uv 将退出并显示错误。

也可以使用 UV_LOCKED 环境变量设置。

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

--no-annotate

排除指示每个软件包来源的注释

不要安装预构建的 wheel 包。

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

也可以使用 UV_NO_BINARY 环境变量设置。

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

不要安装特定包的预构建 wheel 包

也可以使用 UV_NO_BINARY_PACKAGE 环境变量设置。

不要构建源分发包。

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

也可以使用 UV_NO_BUILD 环境变量设置。

构建源分发包时禁用隔离。

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

也可以使用 UV_NO_BUILD_ISOLATION 环境变量设置。

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

为特定包构建源分发包时禁用隔离。

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

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

不要构建特定包的源分发包

也可以使用 UV_NO_BUILD_PACKAGE 环境变量设置。

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

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

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

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

也可以使用 UV_NO_CONFIG 环境变量设置。

忽略默认依赖组。

uv 默认包含 tool.uv.default-groups 中定义的组。这将禁用该选项，但是仍然可以使用 --group 包含特定组。

禁用开发依赖组。

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

--no-editable

导出任何可编辑的依赖项，包括项目和任何工作区成员，作为不可编辑项

--no-emit-package, --no-install-package no-emit-package

不发出给定的软件包。

默认情况下，项目的所有依赖项都包含在导出的 requirements 文件中。 --no-emit-package 选项允许排除特定的软件包。

--no-emit-project, --no-install-project

不发出当前项目。

默认情况下，当前项目与其所有依赖项一起包含在导出的 requirements 文件中。 --no-emit-project 选项允许排除项目，但保留其所有依赖项。

--no-emit-workspace, --no-install-workspace

不发出任何工作区成员，包括根项目。

默认情况下，所有工作区成员及其依赖项都包含在导出的 requirements 文件中，以及其所有依赖项。 --no-emit-workspace 选项允许排除所有工作区成员，同时保留其依赖项。

--no-extra no-extra

如果提供了 --all-extras，则排除指定的可选依赖项。

可以多次提供。

--no-group no-group

禁用指定的依赖组。

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

可以多次提供。

--no-hashes

在生成的输出中省略哈希值

--no-header

排除生成的输出文件顶部的注释标题

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

禁用 uv 管理的 Python 版本的使用。

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

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

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

禁用网络访问。

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

也可以使用 UV_OFFLINE 环境变量设置。

仅包括开发依赖组。

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

此选项是 --only-group dev 的别名。暗示 --no-default-groups。

--only-group only-group

仅包括来自指定依赖组的依赖项。

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

可以多次提供。暗示 --no-default-groups。

--output-file, -o output-file

将导出的 requirements 写入给定文件

--package package

导出工作区中特定软件包的依赖项。

如果工作区成员不存在，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 环境变量设置。

--prune package

从依赖项树中修剪给定的软件包。

修剪的软件包将从导出的 requirements 文件中排除，移除修剪的软件包后不再需要的任何依赖项也将被排除。

--python, -p python

解析期间使用的 Python 解释器。

构建源代码分发时需要 Python 解释器，以确定没有 wheels 时的软件包元数据。

如果未设置 requires-python，则解释器也用作最低 Python 版本的后备值。

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

也可以使用 UV_PYTHON 环境变量设置。

--quiet, -q

使用安静输出。

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

刷新所有缓存数据

--refresh-package refresh-package

刷新特定包的缓存数据

--resolution resolution

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

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

也可以使用 UV_RESOLUTION 环境变量设置。

可能的值

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

--script script

导出指定的 PEP 723 Python 脚本的依赖项，而不是当前项目。

如果提供，uv 将根据其内联元数据表解析依赖项，符合 PEP 723。

--upgrade, -U

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

--upgrade-package, -P upgrade-package

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

--verbose, -v

使用详细输出。

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

uv tree

显示项目的依赖树

用法

uv tree [OPTIONS]

Options (选项)

包括来自所有依赖组的依赖项。

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

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

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

可以多次提供。

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

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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 环境变量设置。

--color color-choice

控制输出中颜色的使用。

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

可能的值

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

--config-file config-file

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

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

也可以使用 UV_CONFIG_FILE 环境变量设置。

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

传递给 PEP 517 构建后端的设置，指定为 KEY=VALUE 对

--default-index default-index

默认包索引的 URL（默认情况下：https://pypi.ac.cn/simple）。

接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。

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

也可以使用 UV_DEFAULT_INDEX 环境变量设置。

--depth, -d depth

依赖项树的最大显示深度

[默认值：255]

--directory directory

在运行命令之前更改为给定的目录。

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

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

--exclude-newer exclude-newer

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

接受 RFC 3339 时间戳（例如，2006-12-02T02:07:43Z）和您系统配置时区中相同格式的本地日期（例如，2006-12-02）。

也可以使用 UV_EXCLUDE_NEWER 环境变量设置。

--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 版本选择每个包的最新支持版本

显示 requirements，而不锁定项目。

如果缺少锁定文件，uv 将以错误退出。

也可以使用 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.ac.cn/simple）。

接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。

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

也可以使用 UV_INDEX_URL 环境变量设置。

--invert, --reverse

显示给定软件包的反向依赖项。此标志将反转树并显示依赖于给定软件包的软件包

--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 上的 clone（也称为 Copy-on-Write），以及 Linux 和 Windows 上的 hardlink。

也可以使用 UV_LINK_MODE 环境变量设置。

可能的值

clone：将 wheel 中的包克隆（即，写时复制）到 site-packages 目录中
copy：将 wheel 中的包复制到 site-packages 目录中
hardlink：将 wheel 中的包硬链接到 site-packages 目录中
symlink：将 wheel 中的包符号链接到 site-packages 目录中

断言 uv.lock 将保持不变。

要求锁定文件是最新的。如果锁定文件丢失或需要更新，uv 将退出并显示错误。

也可以使用 UV_LOCKED 环境变量设置。

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

不要安装预构建的 wheel 包。

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

也可以使用 UV_NO_BINARY 环境变量设置。

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

不要安装特定包的预构建 wheel 包

也可以使用 UV_NO_BINARY_PACKAGE 环境变量设置。

不要构建源分发包。

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

也可以使用 UV_NO_BUILD 环境变量设置。

构建源分发包时禁用隔离。

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

也可以使用 UV_NO_BUILD_ISOLATION 环境变量设置。

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

为特定包构建源分发包时禁用隔离。

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

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

不要构建特定包的源分发包

也可以使用 UV_NO_BUILD_PACKAGE 环境变量设置。

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

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

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

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

也可以使用 UV_NO_CONFIG 环境变量设置。

--no-dedupe

不要删除重复的依赖项。通常，当一个软件包已经显示了它的依赖项时，进一步的出现将不会重新显示它的依赖项，并且将包含一个 (*) 以指示它已经被显示。此标志将导致这些重复项被重复显示

忽略默认依赖组。

uv 默认包含 tool.uv.default-groups 中定义的组。这将禁用该选项，但是仍然可以使用 --group 包含特定组。

禁用开发依赖组。

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

--no-group no-group

禁用指定的依赖组。

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

可以多次提供。

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

禁用 uv 管理的 Python 版本的使用。

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

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

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

禁用网络访问。

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

也可以使用 UV_OFFLINE 环境变量设置。

仅包括开发依赖组。

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

此选项是 --only-group dev 的别名。暗示 --no-default-groups。

--only-group only-group

仅包括来自指定依赖组的依赖项。

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

可以多次提供。暗示 --no-default-groups。

--outdated

显示树中每个软件包的最新可用版本

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

--prune prune

从依赖项树的显示中修剪给定的软件包

--python, -p python

用于锁定和过滤的 Python 解释器。

默认情况下，树被过滤以匹配 Python 解释器报告的平台。使用 --universal 显示所有平台的树，或使用 --python-version 或 --python-platform 覆盖标记的子集。

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

也可以使用 UV_PYTHON 环境变量设置。

--python-platform python-platform

过滤树时使用的平台。

例如，传递 --platform windows 以显示在 Windows 上安装时将包含的依赖项。

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

可能的值

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 目标
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 目标
x86_64-unknown-linux-musl：x86_64 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 目标
wasm32-pyodide2024：使用 Pyodide 2024 平台的 wasm32 目标。适用于 Python 3.12

--python-version python-version

过滤树时使用的 Python 版本。

例如，传递 --python-version 3.10 以显示在 Python 3.10 上安装时将包含的依赖项。

默认为发现的 Python 解释器的版本。

--quiet, -q

使用安静输出。

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

--resolution resolution

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

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

也可以使用 UV_RESOLUTION 环境变量设置。

可能的值

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

--script script

显示指定的 PEP 723 Python 脚本的依赖项树，而不是当前项目。

如果提供，uv 将根据其内联元数据表解析依赖项，符合 PEP 723。

--universal

显示平台无关的依赖项树。

显示所有 Python 版本和已解析的软件包版本，而不是过滤到与当前环境相关的版本。

每个软件包可能会显示多个版本。

--upgrade, -U

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

--upgrade-package, -P upgrade-package

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

--verbose, -v

使用详细输出。

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

uv tool

运行和安装 Python 包提供的命令

用法

uv tool [OPTIONS] <COMMAND>

命令

uv tool run: 运行由 Python 软件包提供的命令
uv tool install: 安装由 Python 软件包提供的命令
uv tool upgrade: 升级已安装的工具
uv tool list: 列出已安装的工具
uv tool uninstall: 卸载工具
uv tool update-shell: 确保工具可执行目录在 PATH 上
uv tool dir: 显示 uv 工具目录的路径

uv tool run

运行由 Python 软件包提供的命令。

默认情况下，要安装的软件包被假定为与命令名称匹配。

命令的名称可以包含 <package>@<version> 格式的精确版本，例如，uv tool run [email protected]。如果需要更复杂的版本规范，或者命令由不同的软件包提供，请使用 --from。

uvx 可用于调用 Python，例如，使用 uvx python 或 uvx python@<version>。 Python 解释器将在隔离的虚拟环境中启动。

如果该工具以前已安装，即通过 uv tool install 安装，则将使用已安装的版本，除非请求了版本或使用了 --isolated 标志。

uvx 作为 uv tool run 的便捷别名提供，它们的行为是相同的。

如果没有提供命令，则会显示已安装的工具。

软件包安装到 uv 缓存目录中的临时虚拟环境中。

用法

uv tool run [OPTIONS] [COMMAND]

Options (选项)

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

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

可以多次提供。

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

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

也可以使用 UV_INSECURE_HOST 环境变量设置。

--build-constraints, --build-constraint, -b build-constraints

在构建源代码分发时，使用给定的 requirements 文件约束构建依赖项。

Constraints 文件是类似于 requirements.txt 的文件，它只控制已安装的 requirement 的版本。但是，在 constraints 文件中包含一个软件包不会触发该软件包的安装。

也可以使用 UV_BUILD_CONSTRAINT 环境变量设置。

--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 构建后端的设置，指定为 KEY=VALUE 对

--constraints, --constraint, -c constraints

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

Constraints 文件是类似于 requirements.txt 的文件，它只控制已安装的 requirement 的版本。但是，在 constraints 文件中包含一个软件包不会触发该软件包的安装。

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

也可以使用 UV_CONSTRAINT 环境变量进行设置。

--default-index default-index

默认包索引的 URL（默认情况下：https://pypi.ac.cn/simple）。

接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。

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

也可以使用 UV_DEFAULT_INDEX 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

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

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

--env-file env-file

从 .env 文件加载环境变量。

可以多次提供，后续文件覆盖先前文件中定义的值。

也可以使用 UV_ENV_FILE 环境变量设置。

--exclude-newer exclude-newer

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

接受 RFC 3339 时间戳（例如，2006-12-02T02:07:43Z）和您系统配置时区中相同格式的本地日期（例如，2006-12-02）。

也可以使用 UV_EXCLUDE_NEWER 环境变量设置。

--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 版本选择每个包的最新支持版本

--from from

使用给定的软件包来提供命令。

默认情况下，软件包名称被假定为与命令名称匹配。

--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.ac.cn/simple）。

接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。

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

也可以使用 UV_INDEX_URL 环境变量设置。

--isolated

在隔离的虚拟环境中运行工具，忽略任何已安装的工具

--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 上的 clone（也称为 Copy-on-Write），以及 Linux 和 Windows 上的 hardlink。

也可以使用 UV_LINK_MODE 环境变量设置。

可能的值

clone：将 wheel 中的包克隆（即，写时复制）到 site-packages 目录中
copy：将 wheel 中的包复制到 site-packages 目录中
hardlink：将 wheel 中的包硬链接到 site-packages 目录中
symlink：将 wheel 中的包符号链接到 site-packages 目录中

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

不要安装预构建的 wheel 包。

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

也可以使用 UV_NO_BINARY 环境变量设置。

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

不要安装特定包的预构建 wheel 包

也可以使用 UV_NO_BINARY_PACKAGE 环境变量设置。

不要构建源分发包。

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

也可以使用 UV_NO_BUILD 环境变量设置。

构建源分发包时禁用隔离。

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

也可以使用 UV_NO_BUILD_ISOLATION 环境变量设置。

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

为特定包构建源分发包时禁用隔离。

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

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

不要构建特定包的源分发包

也可以使用 UV_NO_BUILD_PACKAGE 环境变量设置。

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

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

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

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

也可以使用 UV_NO_CONFIG 环境变量设置。

--no-env-file

避免从 .env 文件读取环境变量

也可以使用 UV_NO_ENV_FILE 环境变量设置。

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

禁用 uv 管理的 Python 版本的使用。

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

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

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

禁用网络访问。

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

也可以使用 UV_OFFLINE 环境变量设置。

--overrides, --override overrides

使用给定的 requirements 文件覆盖版本。

Overrides 文件是类似于 requirements.txt 的文件，它强制安装 requirement 的特定版本，而不管任何组成软件包声明的 requirements，也不管这是否被认为是无效的解析。

虽然 constraints 是附加的，因为它们与组成软件包的 requirements 相结合，但 overrides 是绝对的，因为它们完全替换了组成软件包的 requirements。

也可以使用 UV_OVERRIDE 环境变量设置。

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

刷新所有缓存数据

--refresh-package refresh-package

刷新特定包的缓存数据

--reinstall, --force-reinstall

重新安装所有包，无论它们是否已经安装。暗示 --refresh

--reinstall-package reinstall-package

重新安装特定包，无论它是否已经安装。暗示 --refresh-package

--resolution resolution

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

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

也可以使用 UV_RESOLUTION 环境变量设置。

可能的值

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

--upgrade, -U

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

--upgrade-package, -P upgrade-package

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

--verbose, -v

使用详细输出。

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

--with, -w with

使用已安装的给定软件包运行

--with-editable with-editable

使用以可编辑模式安装的给定软件包运行

在项目中使用时，这些依赖项将以单独的临时环境分层在 uv 工具环境之上。这些依赖项可以与指定的依赖项冲突。

--with-requirements with-requirements

使用给定的 requirements.txt 文件中列出的所有软件包运行

uv tool install

安装由 Python 软件包提供的命令。

软件包安装到 uv 工具目录中的隔离虚拟环境中。可执行文件链接到工具可执行目录，该目录根据 XDG 标准确定，可以使用 uv tool dir --bin 检索。

如果该工具以前已安装，则现有工具通常会被替换。

用法

uv tool install [OPTIONS] <PACKAGE>

参数

PACKAGE: 从中安装命令的软件包

Options (选项)

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

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

可以多次提供。

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

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

也可以使用 UV_INSECURE_HOST 环境变量设置。

--build-constraints, --build-constraint, -b build-constraints

在构建源代码分发时，使用给定的 requirements 文件约束构建依赖项。

Constraints 文件是类似于 requirements.txt 的文件，它只控制已安装的 requirement 的版本。但是，在 constraints 文件中包含一个软件包不会触发该软件包的安装。

也可以使用 UV_BUILD_CONSTRAINT 环境变量设置。

--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 构建后端的设置，指定为 KEY=VALUE 对

--constraints, --constraint, -c constraints

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

Constraints 文件是类似于 requirements.txt 的文件，它只控制已安装的 requirement 的版本。但是，在 constraints 文件中包含一个软件包不会触发该软件包的安装。

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

也可以使用 UV_CONSTRAINT 环境变量进行设置。

--default-index default-index

默认包索引的 URL（默认情况下：https://pypi.ac.cn/simple）。

接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。

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

也可以使用 UV_DEFAULT_INDEX 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

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

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

--editable, -e

以可编辑模式安装目标软件包，这样，在不重新安装的情况下，软件包源代码目录中的更改就会反映出来

--exclude-newer exclude-newer

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

接受 RFC 3339 时间戳（例如，2006-12-02T02:07:43Z）和您系统配置时区中相同格式的本地日期（例如，2006-12-02）。

也可以使用 UV_EXCLUDE_NEWER 环境变量设置。

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

--force

强制安装该工具。

将替换可执行目录中具有相同名称的任何现有入口点。

--fork-strategy fork-strategy

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

默认情况下，uv 将优化为为每个支持的 Python 版本 (requires-python) 选择每个包的最新版本，同时最大限度地减少跨平台选择的版本数量。

在 fewest 下，uv 将最大限度地减少每个包选择的版本数量，优先选择与更广泛的支持的 Python 版本或平台兼容的旧版本。

也可以使用 UV_FORK_STRATEGY 环境变量设置。

可能的值

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

--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.ac.cn/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 命令进行凭据查找

--link-mode link-mode

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

默认为 macOS 上的 clone（也称为 Copy-on-Write），以及 Linux 和 Windows 上的 hardlink。

也可以使用 UV_LINK_MODE 环境变量设置。

可能的值

clone：将 wheel 中的包克隆（即，写时复制）到 site-packages 目录中
copy：将 wheel 中的包复制到 site-packages 目录中
hardlink：将 wheel 中的包硬链接到 site-packages 目录中
symlink：将 wheel 中的包符号链接到 site-packages 目录中

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

不要安装预构建的 wheel 包。

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

也可以使用 UV_NO_BINARY 环境变量设置。

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

不要安装特定包的预构建 wheel 包

也可以使用 UV_NO_BINARY_PACKAGE 环境变量设置。

不要构建源分发包。

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

也可以使用 UV_NO_BUILD 环境变量设置。

构建源分发包时禁用隔离。

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

也可以使用 UV_NO_BUILD_ISOLATION 环境变量设置。

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

为特定包构建源分发包时禁用隔离。

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

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

不要构建特定包的源分发包

也可以使用 UV_NO_BUILD_PACKAGE 环境变量设置。

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

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

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

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

也可以使用 UV_NO_CONFIG 环境变量设置。

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

禁用 uv 管理的 Python 版本的使用。

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

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

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

禁用网络访问。

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

也可以使用 UV_OFFLINE 环境变量设置。

--overrides, --override overrides

使用给定的 requirements 文件覆盖版本。

Overrides 文件是类似于 requirements.txt 的文件，它强制安装 requirement 的特定版本，而不管任何组成软件包声明的 requirements，也不管这是否被认为是无效的解析。

虽然 constraints 是附加的，因为它们与组成软件包的 requirements 相结合，但 overrides 是绝对的，因为它们完全替换了组成软件包的 requirements。

也可以使用 UV_OVERRIDE 环境变量设置。

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

刷新所有缓存数据

--refresh-package refresh-package

刷新特定包的缓存数据

--reinstall, --force-reinstall

重新安装所有包，无论它们是否已经安装。暗示 --refresh

--reinstall-package reinstall-package

重新安装特定包，无论它是否已经安装。暗示 --refresh-package

--resolution resolution

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

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

也可以使用 UV_RESOLUTION 环境变量设置。

可能的值

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

--upgrade, -U

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

--upgrade-package, -P upgrade-package

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

--verbose, -v

使用详细输出。

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

--with, -w with

包括以下附加 requirement

--with-editable with-editable

以可编辑模式包含给定的软件包

--with-requirements with-requirements

包括给定的 requirements.txt 文件中列出的所有 requirements

uv tool upgrade

升级已安装的工具。

如果工具是使用版本 constraints 安装的，则在升级时会遵守这些 constraints — 要将工具升级到超出最初提供的 constraints 之外，请再次使用 uv tool install。

如果工具是使用特定设置安装的，则在升级时会遵守这些设置。例如，如果在安装期间提供了 --prereleases allow，则在升级中将继续遵守。

用法

uv tool upgrade [OPTIONS] <NAME>...

参数

NAME: 要升级的工具的名称，以及可选的版本说明符

Options (选项)

--all

升级所有工具

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

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

可以多次提供。

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

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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 环境变量设置。

--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 构建后端的设置，指定为 KEY=VALUE 对

--default-index default-index

默认包索引的 URL（默认情况下：https://pypi.ac.cn/simple）。

接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。

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

也可以使用 UV_DEFAULT_INDEX 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

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

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

--exclude-newer exclude-newer

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

接受 RFC 3339 时间戳（例如，2006-12-02T02:07:43Z）和您系统配置时区中相同格式的本地日期（例如，2006-12-02）。

也可以使用 UV_EXCLUDE_NEWER 环境变量设置。

--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 版本选择每个包的最新支持版本

--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.ac.cn/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 命令进行凭据查找

--link-mode link-mode

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

默认为 macOS 上的 clone（也称为 Copy-on-Write），以及 Linux 和 Windows 上的 hardlink。

也可以使用 UV_LINK_MODE 环境变量设置。

可能的值

clone：将 wheel 中的包克隆（即，写时复制）到 site-packages 目录中
copy：将 wheel 中的包复制到 site-packages 目录中
hardlink：将 wheel 中的包硬链接到 site-packages 目录中
symlink：将 wheel 中的包符号链接到 site-packages 目录中

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

不要安装预构建的 wheel 包。

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

也可以使用 UV_NO_BINARY 环境变量设置。

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

不要安装特定包的预构建 wheel 包

也可以使用 UV_NO_BINARY_PACKAGE 环境变量设置。

不要构建源分发包。

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

也可以使用 UV_NO_BUILD 环境变量设置。

构建源分发包时禁用隔离。

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

也可以使用 UV_NO_BUILD_ISOLATION 环境变量设置。

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

为特定包构建源分发包时禁用隔离。

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

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

不要构建特定包的源分发包

也可以使用 UV_NO_BUILD_PACKAGE 环境变量设置。

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

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

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

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

也可以使用 UV_NO_CONFIG 环境变量设置。

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

禁用 uv 管理的 Python 版本的使用。

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

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

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

禁用网络访问。

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

也可以使用 UV_OFFLINE 环境变量设置。

--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 解释器来构建其环境。与 --all 一起使用可应用于所有工具。

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

也可以使用 UV_PYTHON 环境变量设置。

--quiet, -q

使用安静输出。

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

--reinstall, --force-reinstall

重新安装所有包，无论它们是否已经安装。暗示 --refresh

--reinstall-package reinstall-package

重新安装特定包，无论它是否已经安装。暗示 --refresh-package

--resolution resolution

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

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

也可以使用 UV_RESOLUTION 环境变量设置。

可能的值

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

--verbose, -v

使用详细输出。

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

uv tool list

列出已安装的工具

用法

uv tool list [OPTIONS]

Options (选项)

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

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

可以多次提供。

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

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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 环境变量设置。

--color color-choice

控制输出中颜色的使用。

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

可能的值

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

--config-file config-file

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

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

也可以使用 UV_CONFIG_FILE 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

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

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

--help, -h

显示此命令的简明帮助

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

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

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

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

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

也可以使用 UV_NO_CONFIG 环境变量设置。

禁用 uv 管理的 Python 版本的使用。

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

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

--show-version-specifiers

禁用网络访问。

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

也可以使用 UV_OFFLINE 环境变量设置。

--project project

在给定的项目目录中运行命令。

所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境 (.venv) 也会被发现。

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

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

此设置在 uv pip 界面中使用时无效。

也可以使用 UV_PROJECT 环境变量设置。

--quiet, -q

使用安静输出。

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

--show-extras

是否显示随每个工具安装的额外需求

--show-paths

是否显示每个工具环境和已安装可执行文件的路径

是否显示用于安装每个工具的版本说明符

--show-with

是否显示随每个工具安装的额外需求

--verbose, -v

使用详细输出。

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

uv tool uninstall

卸载工具

用法

uv tool uninstall [OPTIONS] <NAME>...

参数

NAME: 要卸载的工具的名称

Options (选项)

--all

卸载所有工具

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

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

可以多次提供。

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

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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 环境变量设置。

--color color-choice

控制输出中颜色的使用。

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

可能的值

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

--config-file config-file

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

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

也可以使用 UV_CONFIG_FILE 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

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

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

--help, -h

显示此命令的简明帮助

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

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

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

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

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

也可以使用 UV_NO_CONFIG 环境变量设置。

禁用 uv 管理的 Python 版本的使用。

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

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

禁用网络访问。

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

也可以使用 UV_OFFLINE 环境变量设置。

--project project

在给定的项目目录中运行命令。

所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境 (.venv) 也会被发现。

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

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

此设置在 uv pip 界面中使用时无效。

也可以使用 UV_PROJECT 环境变量设置。

--quiet, -q

使用安静输出。

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

--verbose, -v

使用详细输出。

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

uv tool update-shell

确保工具可执行文件目录位于 PATH 上。

如果工具可执行文件目录不在 PATH 上，uv 将尝试将其添加到相关的 shell 配置文件中。

如果 shell 配置文件已经包含将可执行文件目录添加到路径的说明，但该目录不在 PATH 上，uv 将退出并显示错误。

工具可执行文件目录根据 XDG 标准确定，可以使用 uv tool dir --bin 检索。

用法

uv tool update-shell [OPTIONS]

Options (选项)

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

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

可以多次提供。

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

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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 环境变量设置。

--color color-choice

控制输出中颜色的使用。

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

可能的值

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

--config-file config-file

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

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

也可以使用 UV_CONFIG_FILE 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

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

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

--help, -h

显示此命令的简明帮助

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

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

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

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

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

也可以使用 UV_NO_CONFIG 环境变量设置。

禁用 uv 管理的 Python 版本的使用。

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

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

禁用网络访问。

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

也可以使用 UV_OFFLINE 环境变量设置。

--project project

在给定的项目目录中运行命令。

所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境 (.venv) 也会被发现。

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

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

此设置在 uv pip 界面中使用时无效。

也可以使用 UV_PROJECT 环境变量设置。

--quiet, -q

使用安静输出。

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

--verbose, -v

使用详细输出。

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

uv tool dir

显示 uv 工具目录的路径。

工具目录用于存储已安装工具的环境和元数据。

默认情况下，工具存储在 uv 数据目录中，Unix 上为 $XDG_DATA_HOME/uv/tools 或 $HOME/.local/share/uv/tools，Windows 上为 %APPDATA%\uv\data\tools。

可以使用 $UV_TOOL_DIR 覆盖工具安装目录。

要查看 uv 安装可执行文件的目录，请使用 --bin 标志。

用法

uv tool dir [OPTIONS]

Options (选项)

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

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

可以多次提供。

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

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

也可以使用 UV_INSECURE_HOST 环境变量设置。

--bin

显示 uv tool 将安装可执行文件的目录。

默认情况下，uv tool dir 显示安装工具 Python 环境本身的目录，而不是包含链接的可执行文件的目录。

工具可执行文件目录根据 XDG 标准确定，并从以下环境变量派生，按优先级顺序排列

$UV_TOOL_BIN_DIR
$XDG_BIN_HOME
$XDG_DATA_HOME/../bin
$HOME/.local/bin

--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：禁用彩色输出

--config-file config-file

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

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

也可以使用 UV_CONFIG_FILE 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

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

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

--help, -h

显示此命令的简明帮助

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

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

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

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

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

也可以使用 UV_NO_CONFIG 环境变量设置。

禁用 uv 管理的 Python 版本的使用。

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

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

禁用网络访问。

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

也可以使用 UV_OFFLINE 环境变量设置。

--project project

在给定的项目目录中运行命令。

所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境 (.venv) 也会被发现。

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

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

此设置在 uv pip 界面中使用时无效。

也可以使用 UV_PROJECT 环境变量设置。

--quiet, -q

使用安静输出。

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

--verbose, -v

使用详细输出。

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

uv python

管理 Python 版本和安装

通常，uv 首先在虚拟环境中搜索 Python，无论是活动的还是在当前工作目录或任何父目录中的 .venv 目录中。如果不需要虚拟环境，uv 然后将搜索 Python 解释器。 Python 解释器通过在 PATH 环境变量中搜索 Python 可执行文件来找到。

在 Windows 上，也会在注册表中搜索 Python 可执行文件。

默认情况下，如果找不到 Python 版本，uv 将下载 Python。可以使用 --no-python-downloads 标志或 python-downloads 设置禁用此行为。

--python 选项允许请求不同的解释器。

支持以下 Python 版本请求格式

<version> 例如 3, 3.12, 3.12.3
<version-specifier> 例如 >=3.12,<3.13
<implementation> 例如 cpython 或 cp
<implementation>@<version> 例如 [email protected]
<implementation><version> 例如 cpython3.12 或 cp312
<implementation><version-specifier> 例如 cpython>=3.12,<3.13
<implementation>-<version>-<os>-<arch>-<libc> 例如 cpython-3.12.3-macos-aarch64-none

此外，通常可以使用以下方式请求特定的系统 Python 解释器

<executable-path> 例如 /opt/homebrew/bin/python3
<executable-name> 例如 mypython3
<install-dir> 例如 /some/environment/

当使用 --python 选项时，应用正常的发现规则，但会检查发现的解释器与请求的兼容性，例如，如果请求 pypy，uv 将首先检查虚拟环境是否包含 PyPy 解释器，然后检查路径中的每个可执行文件是否都是 PyPy 解释器。

uv 支持发现 CPython、PyPy 和 GraalPy 解释器。不支持的解释器将在发现期间被跳过。如果请求了不支持的解释器实现，uv 将退出并显示错误。

用法

uv python [OPTIONS] <COMMAND>

命令

uv python list: 列出可用的 Python 安装
uv python install: 下载并安装 Python 版本
uv python upgrade: 将已安装的 Python 版本升级到最新的受支持补丁版本（需要 --preview 标志）
uv python find: 搜索 Python 安装
uv python pin: 锁定到特定的 Python 版本
uv python dir: 显示 uv Python 安装目录
uv python uninstall: 卸载 Python 版本
uv python update-shell: 确保 Python 可执行文件目录位于 PATH 上

uv python list

列出可用的 Python 安装。

默认情况下，显示已安装的 Python 版本和每个支持的 Python 主要版本的最新可用补丁版本的下载。

使用 --managed-python 仅查看托管的 Python 版本。

使用 --no-managed-python 省略托管的 Python 版本。

使用 --all-versions 查看所有可用的补丁版本。

使用 --only-installed 省略可用下载。

用法

uv python list [OPTIONS] [REQUEST]

参数

REQUEST

用于筛选的 Python 请求。

请参阅 uv python 以查看支持的请求格式。

Options (选项)

--all-arches, --all_architectures

列出所有架构的 Python 下载。

默认情况下，仅显示当前架构的下载。

--all-platforms

列出所有平台的 Python 下载。

默认情况下，仅显示当前平台的下载。

--all-versions

列出所有 Python 版本，包括旧的补丁版本。

默认情况下，每个次要版本仅显示最新的补丁版本。

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

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

可以多次提供。

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

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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 环境变量设置。

--color color-choice

控制输出中颜色的使用。

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

可能的值

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

--config-file config-file

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

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

也可以使用 UV_CONFIG_FILE 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

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

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

--help, -h

显示此命令的简明帮助

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

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

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

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

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

也可以使用 UV_NO_CONFIG 环境变量设置。

禁用 uv 管理的 Python 版本的使用。

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

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

禁用网络访问。

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

也可以使用 UV_OFFLINE 环境变量设置。

--only-downloads

仅显示可用的 Python 下载。

默认情况下，显示当前平台上已安装的发行版和可用的下载。

--only-installed

仅显示已安装的 Python 版本。

默认情况下，显示当前平台上已安装的发行版和可用的下载。

--output-format output-format

选择输出格式

[默认：文本]

可能的值

text：纯文本（供人阅读）
json：JSON（供计算机阅读）

--project project

在给定的项目目录中运行命令。

所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境 (.venv) 也会被发现。

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

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

此设置在 uv pip 界面中使用时无效。

也可以使用 UV_PROJECT 环境变量设置。

--python-downloads-json-url python-downloads-json-url

指向自定义 Python 安装 JSON 的 URL。

请注意，目前仅支持本地路径。

也可以使用 UV_PYTHON_DOWNLOADS_JSON_URL 环境变量设置。

--quiet, -q

使用安静输出。

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

--show-urls

显示可用 Python 下载的 URL。

默认情况下，这些显示为 <download available>。

--verbose, -v

使用详细输出。

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

uv python install

下载并安装 Python 版本。

支持 CPython 和 PyPy。 CPython 发行版从 Astral python-build-standalone 项目下载。 PyPy 发行版从 python.org 下载。可用的 Python 版本与每个 uv 版本捆绑在一起。要安装新的 Python 版本，可能需要升级 uv。

Python 版本安装到 uv Python 目录中，可以使用 uv python dir 检索。

默认情况下，Python 可执行文件会添加到路径上的目录中，并带有次要版本后缀，例如 python3.13。要安装 python3 和 python，请使用 --default 标志。使用 uv python dir --bin 查看目标目录。

可以请求多个 Python 版本。

请参阅 uv help python 以查看支持的请求格式。

用法

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

参数

TARGETS

要安装的 Python 版本。

如果未提供，则请求的 Python 版本将从 UV_PYTHON 环境变量读取，然后从 .python-versions 或 .python-version 文件读取。如果以上任何一个都不存在，uv 将检查它是否已安装任何 Python 版本。如果没有，它将安装最新的稳定 Python 版本。

请参阅 uv python 以查看支持的请求格式。

Options (选项)

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

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

可以多次提供。

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

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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 环境变量设置。

--color color-choice

控制输出中颜色的使用。

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

可能的值

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

--config-file config-file

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

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

也可以使用 UV_CONFIG_FILE 环境变量设置。

--default

用作默认 Python 版本。

默认情况下，仅安装 python{major}.{minor} 可执行文件，例如 python3.10。当使用 --default 标志时，也会安装 python{major}（例如 python3）和 python 可执行文件。

替代 Python 变体仍将包含它们的标签。例如，使用 --default 安装 3.13+freethreaded 将包括 python3t 和 pythont，而不是 python3 和 python。

如果请求多个 Python 版本，uv 将退出并显示错误。

--directory directory

在运行命令之前更改为给定的目录。

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

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

--force, -f

在安装过程中替换现有的 Python 可执行文件。

默认情况下，uv 将拒绝替换它不管理的可执行文件。

暗示 --reinstall。

--help, -h

显示此命令的简明帮助

--install-dir, -i install-dir

存储 Python 安装的目录。

如果提供，需要为后续操作设置 UV_PYTHON_INSTALL_DIR，以便 uv 发现 Python 安装。

请参阅 uv python dir 以查看当前的 Python 安装目录。默认为 ~/.local/share/uv/python。

也可以使用 UV_PYTHON_INSTALL_DIR 环境变量设置。

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

--mirror mirror

设置要用作下载 Python 安装源的 URL。

提供的 URL 将替换 https://github.com/astral-sh/python-build-standalone/releases/download，例如 https://github.com/astral-sh/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz。

可以通过使用 file:// URL 方案从本地目录读取发行版。

也可以使用 UV_PYTHON_INSTALL_MIRROR 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

--no-bin

不要将 Python 可执行文件安装到 bin 目录中。

也可以使用 UV_PYTHON_INSTALL_BIN=0 设置。

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

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

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

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

也可以使用 UV_NO_CONFIG 环境变量设置。

禁用 uv 管理的 Python 版本的使用。

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

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

--no-registry

不要在 Windows 注册表中注册 Python 安装。

也可以使用 UV_PYTHON_INSTALL_REGISTRY=0 设置。

禁用网络访问。

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

也可以使用 UV_OFFLINE 环境变量设置。

--project project

在给定的项目目录中运行命令。

所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境 (.venv) 也会被发现。

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

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

此设置在 uv pip 界面中使用时无效。

也可以使用 UV_PROJECT 环境变量设置。

--pypy-mirror pypy-mirror

设置要用作下载 PyPy 安装源的 URL。

提供的 URL 将替换 https://downloads.python.org/pypy，例如 https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2。

可以通过使用 file:// URL 方案从本地目录读取发行版。

也可以使用 UV_PYPY_INSTALL_MIRROR 环境变量设置。

--python-downloads-json-url python-downloads-json-url

指向自定义 Python 安装 JSON 的 URL。

请注意，目前仅支持本地路径。

也可以使用 UV_PYTHON_DOWNLOADS_JSON_URL 环境变量设置。

--quiet, -q

使用安静输出。

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

--reinstall, -r

如果已安装，则重新安装请求的 Python 版本。

默认情况下，如果已安装该版本，uv 将成功退出。

--verbose, -v

使用详细输出。

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

uv python upgrade

将已安装的 Python 版本升级到最新的受支持补丁版本（需要 --preview 标志）。

可以提供要升级的目标 Python 次要版本，例如 3.13。可以提供多个版本来执行多次升级。

如果未提供目标版本，则 uv 将升级所有托管的 CPython 版本。

在升级期间，uv 不会卸载过时的补丁版本。

执行升级后，uv 创建的虚拟环境将自动使用新版本。但是，如果在添加升级功能之前创建了虚拟环境，它将继续使用旧的 Python 版本；要启用升级，必须重新创建环境。

替代实现（如 PyPy）尚不支持升级。

用法

uv python upgrade [OPTIONS] [TARGETS]...

参数

TARGETS

要升级的 Python 次要版本。

如果未提供目标版本，则 uv 将升级所有托管的 CPython 版本。

Options (选项)

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

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

可以多次提供。

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

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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 环境变量设置。

--color color-choice

控制输出中颜色的使用。

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

可能的值

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

--config-file config-file

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

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

也可以使用 UV_CONFIG_FILE 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

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

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

--help, -h

显示此命令的简明帮助

--install-dir, -i install-dir

Python 安装存储在的目录。

如果提供，需要为后续操作设置 UV_PYTHON_INSTALL_DIR，以便 uv 发现 Python 安装。

请参阅 uv python dir 以查看当前的 Python 安装目录。默认为 ~/.local/share/uv/python。

也可以使用 UV_PYTHON_INSTALL_DIR 环境变量设置。

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

--mirror mirror

设置要用作下载 Python 安装源的 URL。

提供的 URL 将替换 https://github.com/astral-sh/python-build-standalone/releases/download，例如 https://github.com/astral-sh/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz。

可以通过使用 file:// URL 方案从本地目录读取发行版。

也可以使用 UV_PYTHON_INSTALL_MIRROR 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

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

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

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

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

也可以使用 UV_NO_CONFIG 环境变量设置。

禁用 uv 管理的 Python 版本的使用。

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

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

禁用网络访问。

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

也可以使用 UV_OFFLINE 环境变量设置。

--project project

在给定的项目目录中运行命令。

所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境 (.venv) 也会被发现。

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

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

此设置在 uv pip 界面中使用时无效。

也可以使用 UV_PROJECT 环境变量设置。

--pypy-mirror pypy-mirror

设置要用作下载 PyPy 安装源的 URL。

提供的 URL 将替换 https://downloads.python.org/pypy，例如 https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2。

可以通过使用 file:// URL 方案从本地目录读取发行版。

也可以使用 UV_PYPY_INSTALL_MIRROR 环境变量设置。

--python-downloads-json-url python-downloads-json-url

指向自定义 Python 安装 JSON 的 URL。

请注意，目前仅支持本地路径。

也可以使用 UV_PYTHON_DOWNLOADS_JSON_URL 环境变量设置。

--quiet, -q

使用安静输出。

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

--verbose, -v

使用详细输出。

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

uv python find

搜索 Python 安装。

显示 Python 可执行文件的路径。

请参阅 uv help python 以查看支持的请求格式和有关发现行为的详细信息。

用法

uv python find [OPTIONS] [REQUEST]

参数

REQUEST

Python 请求。

请参阅 uv python 以查看支持的请求格式。

Options (选项)

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

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

可以多次提供。

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

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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 环境变量设置。

--color color-choice

控制输出中颜色的使用。

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

可能的值

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

--config-file config-file

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

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

也可以使用 UV_CONFIG_FILE 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

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

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

--help, -h

显示此命令的简明帮助

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

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

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

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

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

也可以使用 UV_NO_CONFIG 环境变量设置。

禁用 uv 管理的 Python 版本的使用。

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

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

--no-project, --no_workspace

避免发现项目或工作区。

否则，当没有提供请求时，将使用当前目录或父目录中项目的 Python 要求。

禁用 Python 的自动下载。

禁用网络访问。

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

也可以使用 UV_OFFLINE 环境变量设置。

--project project

在给定的项目目录中运行命令。

所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境 (.venv) 也会被发现。

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

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

此设置在 uv pip 界面中使用时无效。

也可以使用 UV_PROJECT 环境变量设置。

--quiet, -q

使用安静输出。

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

--script script

查找 Python 脚本的环境，而不是当前项目

--show-version

显示将使用的 Python 版本，而不是解释器的路径

仅查找系统 Python 解释器。

默认情况下，uv 将报告它将使用的第一个 Python 解释器，包括活动虚拟环境中的解释器或当前工作目录或任何父目录中的虚拟环境中的解释器。

--system 选项指示 uv 跳过虚拟环境 Python 解释器，并将其搜索限制为系统路径。

也可以使用 UV_SYSTEM_PYTHON 环境变量设置。

--verbose, -v

使用详细输出。

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

uv python pin

锁定到特定的 Python 版本。

将锁定的 Python 版本写入 .python-version 文件，其他 uv 命令使用该文件来确定所需的 Python 版本。

如果没有提供版本，uv 将查找现有的 .python-version 文件并显示当前锁定的版本。如果没有找到 .python-version 文件，uv 将退出并显示错误。

请参阅 uv help python 以查看支持的请求格式。

用法

uv python pin [OPTIONS] [REQUEST]

参数

REQUEST

Python 版本请求。

uv 支持比其他读取 .python-version 文件的工具（例如 pyenv）更多的格式。如果需要与这些工具兼容，请仅使用版本号，而不是复杂的请求，例如 [email protected]。

如果没有提供请求，将显示当前锁定的版本。

请参阅 uv python 以查看支持的请求格式。

Options (选项)

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

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

可以多次提供。

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

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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 环境变量设置。

--color color-choice

控制输出中颜色的使用。

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

可能的值

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

--config-file config-file

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

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

也可以使用 UV_CONFIG_FILE 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

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

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

--global

更新全局 Python 版本锁定。

将锁定的 Python 版本写入 uv 用户配置文件中的 .python-version 文件：Linux/macOS 上的 XDG_CONFIG_HOME/uv 和 Windows 上的 %APPDATA%/uv。

如果在工作目录或祖先目录中找不到本地 Python 版本锁定，则将使用此版本。

--help, -h

显示此命令的简明帮助

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

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

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

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

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

也可以使用 UV_NO_CONFIG 环境变量设置。

禁用 uv 管理的 Python 版本的使用。

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

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

--no-project, --no-workspace

避免验证 Python 锁定是否与项目或工作区兼容。

默认情况下，将在当前目录或任何父目录中发现项目或工作区。如果找到工作区，Python 锁定将根据工作区的 requires-python 约束进行验证。

禁用 Python 的自动下载。

禁用网络访问。

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

也可以使用 UV_OFFLINE 环境变量设置。

--project project

在给定的项目目录中运行命令。

所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境 (.venv) 也会被发现。

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

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

此设置在 uv pip 界面中使用时无效。

也可以使用 UV_PROJECT 环境变量设置。

--quiet, -q

使用安静输出。

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

--resolved

写入已解析的 Python 解释器路径，而不是请求。

确保使用完全相同的解释器。

将 .python-version 文件提交到版本控制时，此选项通常不安全使用。

--rm

删除 Python 版本锁定

--verbose, -v

使用详细输出。

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

uv python dir

显示 uv Python 安装目录。

默认情况下，Python 安装存储在 uv 数据目录中，Unix 上的 $XDG_DATA_HOME/uv/python 或 $HOME/.local/share/uv/python，Windows 上的 %APPDATA%\uv\data\python。

可以使用 $UV_PYTHON_INSTALL_DIR 覆盖 Python 安装目录。

要查看 uv 安装 Python 可执行文件的目录，请使用 --bin 标志。可以使用 $UV_PYTHON_BIN_DIR 覆盖 Python 可执行文件目录。请注意，仅在启用预览模式时才安装 Python 可执行文件。

用法

uv python dir [OPTIONS]

Options (选项)

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

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

可以多次提供。

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

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

也可以使用 UV_INSECURE_HOST 环境变量设置。

--bin

显示 uv python 将安装 Python 可执行文件的目录。

请注意，仅在启用预览模式安装 Python 时才使用此目录。

Python 可执行文件目录根据 XDG 标准确定，并从以下环境变量派生，按优先级顺序排列

$UV_PYTHON_BIN_DIR
$XDG_BIN_HOME
$XDG_DATA_HOME/../bin
$HOME/.local/bin

--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：禁用彩色输出

--config-file config-file

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

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

也可以使用 UV_CONFIG_FILE 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

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

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

--help, -h

显示此命令的简明帮助

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

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

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

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

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

也可以使用 UV_NO_CONFIG 环境变量设置。

禁用 uv 管理的 Python 版本的使用。

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

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

禁用网络访问。

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

也可以使用 UV_OFFLINE 环境变量设置。

--project project

在给定的项目目录中运行命令。

所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境 (.venv) 也会被发现。

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

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

此设置在 uv pip 界面中使用时无效。

也可以使用 UV_PROJECT 环境变量设置。

--quiet, -q

使用安静输出。

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

--verbose, -v

使用详细输出。

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

uv python uninstall

卸载 Python 版本

用法

uv python uninstall [OPTIONS] <TARGETS>...

参数

TARGETS

要卸载的 Python 版本。

请参阅 uv python 以查看支持的请求格式。

Options (选项)

--all

卸载所有托管的 Python 版本

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

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

可以多次提供。

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

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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 环境变量设置。

--color color-choice

控制输出中颜色的使用。

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

可能的值

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

--config-file config-file

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

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

也可以使用 UV_CONFIG_FILE 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

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

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

--help, -h

显示此命令的简明帮助

--install-dir, -i install-dir

安装 Python 的目录

也可以使用 UV_PYTHON_INSTALL_DIR 环境变量设置。

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

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

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

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

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

也可以使用 UV_NO_CONFIG 环境变量设置。

禁用 uv 管理的 Python 版本的使用。

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

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

禁用网络访问。

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

也可以使用 UV_OFFLINE 环境变量设置。

--project project

在给定的项目目录中运行命令。

所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境 (.venv) 也会被发现。

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

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

此设置在 uv pip 界面中使用时无效。

也可以使用 UV_PROJECT 环境变量设置。

--quiet, -q

使用安静输出。

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

--verbose, -v

使用详细输出。

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

uv python update-shell

确保 Python 可执行文件目录位于 PATH 上。

如果 Python 可执行文件目录不在 PATH 上，uv 将尝试将其添加到相关的 shell 配置文件中。

如果 shell 配置文件已经包含将可执行文件目录添加到路径的说明，但该目录不在 PATH 上，uv 将退出并显示错误。

Python 可执行文件目录根据 XDG 标准确定，可以使用 uv python dir --bin 检索。

用法

uv python update-shell [OPTIONS]

Options (选项)

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

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

可以多次提供。

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

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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 环境变量设置。

--color color-choice

控制输出中颜色的使用。

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

可能的值

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

--config-file config-file

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

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

也可以使用 UV_CONFIG_FILE 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

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

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

--help, -h

显示此命令的简明帮助

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

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

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

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

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

也可以使用 UV_NO_CONFIG 环境变量设置。

禁用 uv 管理的 Python 版本的使用。

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

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

禁用网络访问。

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

也可以使用 UV_OFFLINE 环境变量设置。

--project project

在给定的项目目录中运行命令。

所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境 (.venv) 也会被发现。

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

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

此设置在 uv pip 界面中使用时无效。

也可以使用 UV_PROJECT 环境变量设置。

--quiet, -q

使用安静输出。

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

--verbose, -v

使用详细输出。

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

uv pip

使用与 pip 兼容的界面管理 Python 包

用法

uv pip [OPTIONS] <COMMAND>

命令

uv pip compile: 将 requirements.in 文件编译为 requirements.txt 或 pylock.toml 文件
uv pip sync: 将环境与 requirements.txt 或 pylock.toml 文件同步
uv pip install: 将软件包安装到环境中
uv pip uninstall: 从环境中卸载软件包
uv pip freeze: 以 requirements 格式列出环境中安装的软件包
uv pip list: 以表格格式列出环境中安装的软件包
uv pip show: 显示有关一个或多个已安装软件包的信息
uv pip tree: 显示环境的依赖树
uv pip check: 验证已安装的软件包是否具有兼容的依赖项

uv pip compile

将 requirements.in 文件编译为 requirements.txt 或 pylock.toml 文件

用法

uv pip compile [OPTIONS] <SRC_FILE|--group <GROUP>>

参数

SRC_FILE

包括给定 requirements.in 文件中列出的所有软件包。

如果提供了 pyproject.toml、setup.py 或 setup.cfg 文件，uv 将提取相关项目的 requirements。

如果提供了 -，则将从 stdin 读取 requirements。

requirements 文件及其中的 requirements 的顺序用于确定解析期间的优先级。

Options (选项)

--emit-build-options

包括所有可选依赖项。

仅适用于 pyproject.toml、setup.py 和 setup.cfg 源。

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

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

可以多次提供。

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

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

也可以使用 UV_INSECURE_HOST 环境变量设置。

--annotation-style annotation-style

包含在输出文件中的注释样式的注释，用于指示每个软件包的来源。

默认为 split。

可能的值

line：在单个逗号分隔的行上呈现注释
split：在自己的行上呈现每个注释

--build-constraints, --build-constraint, -b build-constraints

在构建源代码分发时，使用给定的 requirements 文件约束构建依赖项。

Constraints 文件是类似于 requirements.txt 的文件，它只控制已安装的 requirement 的版本。但是，在 constraints 文件中包含一个软件包不会触发该软件包的安装。

也可以使用 UV_BUILD_CONSTRAINT 环境变量设置。

--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：禁用彩色输出

--config-file config-file

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

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

也可以使用 UV_CONFIG_FILE 环境变量设置。

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

传递给 PEP 517 构建后端的设置，指定为 KEY=VALUE 对

--constraints, --constraint, -c constraints

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

Constraints 文件是类似于 requirements.txt 的文件，它只控制已安装的 requirement 的版本。但是，在 constraints 文件中包含一个软件包不会触发该软件包的安装。

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

也可以使用 UV_CONSTRAINT 环境变量进行设置。

--custom-compile-command custom-compile-command

在 uv pip compile 生成的输出文件顶部包含的标头注释。

用于反映包装 uv pip compile 的自定义构建脚本和命令。

也可以使用 UV_CUSTOM_COMPILE_COMMAND 环境变量设置。

--default-index default-index

默认包索引的 URL（默认情况下：https://pypi.ac.cn/simple）。

接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。

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

也可以使用 UV_DEFAULT_INDEX 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

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

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

在生成的输出文件中包括 --no-binary 和 --only-binary 条目

--emit-find-links

在生成的输出文件中包括 --find-links 条目

--emit-index-annotation

包括注释注释，指示用于解析每个软件包的索引（例如 # from https://pypi.ac.cn/simple）

--emit-index-url

在生成的输出文件中包括 --index-url 和 --extra-index-url 条目

--exclude-newer exclude-newer

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

接受 RFC 3339 时间戳（例如，2006-12-02T02:07:43Z）和您系统配置时区中相同格式的本地日期（例如，2006-12-02）。

也可以使用 UV_EXCLUDE_NEWER 环境变量设置。

--extra extra

包括来自指定 extra 名称的可选依赖项；可以多次提供。

仅适用于 pyproject.toml、setup.py 和 setup.cfg 源。

--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 版本选择每个包的最新支持版本

--format format

应该输出解析的格式。

支持 requirements.txt 和 pylock.toml (PEP 751) 输出格式。

如果提供，uv 将从输出文件的文件扩展名推断输出格式。否则，默认为 requirements.txt。

可能的值

requirements.txt：以 requirements.txt 格式导出
pylock.toml：以 pylock.toml 格式导出

--generate-hashes

在输出文件中包括发行版哈希

--group group

从 pyproject.toml 安装指定的依赖项组。

如果未提供路径，则使用工作目录中的 pyproject.toml。

可以多次提供。

--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.ac.cn/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 命令进行凭据查找

--link-mode link-mode

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

此选项仅在构建源代码分发时使用。

默认为 macOS 上的 clone（也称为 Copy-on-Write），以及 Linux 和 Windows 上的 hardlink。

也可以使用 UV_LINK_MODE 环境变量设置。

可能的值

clone：将 wheel 中的包克隆（即，写时复制）到 site-packages 目录中
copy：将 wheel 中的包复制到 site-packages 目录中
hardlink：将 wheel 中的包硬链接到 site-packages 目录中
symlink：将 wheel 中的包符号链接到 site-packages 目录中

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

--no-annotate

排除指示每个软件包来源的注释

--no-binary no-binary

不要安装预构建的 wheel 包。

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

可以提供多个包。使用 :all: 禁用所有包的二进制文件。使用 :none: 清除先前指定的包。

不要构建源分发包。

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

--only-binary :all: 的别名。

构建源分发包时禁用隔离。

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

也可以使用 UV_NO_BUILD_ISOLATION 环境变量设置。

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

为特定包构建源分发包时禁用隔离。

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

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

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

也可以使用 UV_NO_CACHE 环境变量设置。

--no-deps

忽略包依赖项，而只将命令行中显式列出的那些包添加到生成的 requirements 文件中

--no-emit-package, --unsafe-package no-emit-package

指定要从输出解析中省略的包。其依赖项仍将包含在解析中。等效于 pip-compile 的 --unsafe-package 选项

--no-header

排除生成的输出文件顶部的注释标题

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

禁用 uv 管理的 Python 版本的使用。

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

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

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

--no-strip-extras

在输出文件中包含 extras。

默认情况下，uv 会去除 extras，因为由 extras 引入的任何包都已经作为依赖项直接包含在输出文件中。此外，使用 --no-strip-extras 生成的输出文件不能在 install 和 sync 调用中用作约束文件。

--no-strip-markers

在输出文件中包含环境标记。

默认情况下，uv 会去除环境标记，因为由 compile 生成的解析仅保证对目标环境正确。

禁用网络访问。

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

也可以使用 UV_OFFLINE 环境变量设置。

--only-binary only-binary

仅使用预构建的 wheels；不要构建源码发行版。

启用后，解析将不会运行来自给定包的代码。已经构建的源码发行版的缓存 wheels 将被重用，但是需要构建发行版的操作将以错误退出。

可以提供多个包。使用 :all: 禁用所有包的二进制文件。使用 :none: 清除先前指定的包。

--output-file, -o output-file

将编译后的 requirements 写入给定的 requirements.txt 或 pylock.toml 文件。

如果文件已经存在，则在解析依赖项时将优先使用现有的版本，除非还指定了 --upgrade。

--overrides, --override overrides

使用给定的 requirements 文件覆盖版本。

Overrides 文件是类似于 requirements.txt 的文件，它强制安装 requirement 的特定版本，而不管任何组成软件包声明的 requirements，也不管这是否被认为是无效的解析。

虽然 constraints 是附加的，因为它们与组成软件包的 requirements 相结合，但 overrides 是绝对的，因为它们完全替换了组成软件包的 requirements。

也可以使用 UV_OVERRIDE 环境变量设置。

--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 解释器，以确定没有 wheels 时的软件包元数据。

除非提供了 --python-version，否则解释器还用于确定默认的最低 Python 版本。

此选项遵循 UV_PYTHON，但是当通过环境变量设置时，它会被 --python-version 覆盖。

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

--python-platform python-platform

应为其解析 requirements 的平台。

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

当以 macOS (Darwin) 为目标时，默认最低版本为 12.0。使用 MACOSX_DEPLOYMENT_TARGET 指定不同的最低版本，例如，13.0。

可能的值

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 目标
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 目标
x86_64-unknown-linux-musl：x86_64 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 目标
wasm32-pyodide2024：使用 Pyodide 2024 平台的 wasm32 目标。适用于 Python 3.12

--python-version python-version

用于解析的 Python 版本。

例如，3.8 或 3.8.17。

默认为用于解析的 Python 解释器的版本。

定义已解析的 requirements 必须支持的最低 Python 版本。

如果省略了补丁版本，则假定为最低补丁版本。例如，3.8 映射到 3.8.0。

--quiet, -q

使用安静输出。

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

刷新所有缓存数据

--refresh-package refresh-package

刷新特定包的缓存数据

--resolution resolution

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

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

也可以使用 UV_RESOLUTION 环境变量设置。

可能的值

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

--allow-empty-requirements

将包安装到系统 Python 环境中。

默认情况下，uv 使用当前工作目录或任何父目录中的虚拟环境，回退到在 PATH 中搜索 Python 可执行文件。 --system 选项指示 uv 避免使用虚拟环境 Python，并将其搜索限制为系统路径。

也可以使用 UV_SYSTEM_PYTHON 环境变量设置。

--torch-backend torch-backend

在 PyTorch 生态系统中获取包时使用的后端（例如，cpu、cu126 或 auto）。

设置后，uv 将忽略 PyTorch 生态系统中包的配置索引 URL，而是使用定义的后端。

例如，当设置为 cpu 时，uv 将使用仅 CPU 的 PyTorch 索引；当设置为 cu126 时，uv 将使用 CUDA 12.6 的 PyTorch 索引。

auto 模式将尝试基于当前安装的 CUDA 驱动程序检测合适的 PyTorch 索引。

此选项处于预览状态，可能会在未来的任何版本中更改。

也可以使用 UV_TORCH_BACKEND 环境变量设置。

可能的值

auto：基于操作系统和 CUDA 驱动程序版本选择合适的 PyTorch 索引
cpu：使用仅 CPU 的 PyTorch 索引
cu128：使用 CUDA 12.8 的 PyTorch 索引
cu126：使用 CUDA 12.6 的 PyTorch 索引
cu125：使用 CUDA 12.5 的 PyTorch 索引
cu124：使用 CUDA 12.4 的 PyTorch 索引
cu123：使用 CUDA 12.3 的 PyTorch 索引
cu122：使用 CUDA 12.2 的 PyTorch 索引
cu121：使用 CUDA 12.1 的 PyTorch 索引
cu120：使用 CUDA 12.0 的 PyTorch 索引
cu118：使用 CUDA 11.8 的 PyTorch 索引
cu117：使用 CUDA 11.7 的 PyTorch 索引
cu116：使用 CUDA 11.6 的 PyTorch 索引
cu115：使用 CUDA 11.5 的 PyTorch 索引
cu114：使用 CUDA 11.4 的 PyTorch 索引
cu113：使用 CUDA 11.3 的 PyTorch 索引
cu112：使用 CUDA 11.2 的 PyTorch 索引
cu111：使用 CUDA 11.1 的 PyTorch 索引
cu110：使用 CUDA 11.0 的 PyTorch 索引
cu102：使用 CUDA 10.2 的 PyTorch 索引
cu101：使用 CUDA 10.1 的 PyTorch 索引
cu100：使用 CUDA 10.0 的 PyTorch 索引
cu92：使用 CUDA 9.2 的 PyTorch 索引
cu91：使用 CUDA 9.1 的 PyTorch 索引
cu90：使用 CUDA 9.0 的 PyTorch 索引
cu80：使用 CUDA 8.0 的 PyTorch 索引
rocm6.3：使用 ROCm 6.3 的 PyTorch 索引
rocm6.2.4：使用 ROCm 6.2.4 的 PyTorch 索引
rocm6.2：使用 ROCm 6.2 的 PyTorch 索引
rocm6.1：使用 ROCm 6.1 的 PyTorch 索引
rocm6.0：使用 ROCm 6.0 的 PyTorch 索引
rocm5.7：使用 ROCm 5.7 的 PyTorch 索引
rocm5.6：使用 ROCm 5.6 的 PyTorch 索引
rocm5.5：使用 ROCm 5.5 的 PyTorch 索引
rocm5.4.2：使用 ROCm 5.4.2 的 PyTorch 索引
rocm5.4：使用 ROCm 5.4 的 PyTorch 索引
rocm5.3：使用 ROCm 5.3 的 PyTorch 索引
rocm5.2：使用 ROCm 5.2 的 PyTorch 索引
rocm5.1.1：使用 ROCm 5.1.1 的 PyTorch 索引
rocm4.2：使用 ROCm 4.2 的 PyTorch 索引
rocm4.1：使用 ROCm 4.1 的 PyTorch 索引
rocm4.0.1：使用 ROCm 4.0.1 的 PyTorch 索引
xpu：使用 Intel XPU 的 PyTorch 索引

--universal

执行通用解析，尝试生成单个与所有操作系统、架构和 Python 实现兼容的 requirements.txt 输出文件。

在通用模式下，当前的 Python 版本（或用户提供的 --python-version）将被视为下限。例如，--universal --python-version 3.7 将为 Python 3.7 及更高版本生成通用解析。

暗示 --no-strip-markers。

--upgrade, -U

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

--upgrade-package, -P upgrade-package

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

--verbose, -v

使用详细输出。

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

uv pip sync

将环境与 requirements.txt 或 pylock.toml 文件同步。

同步环境时，将删除 requirements.txt 或 pylock.toml 文件中未列出的任何包。要保留无关的包，请改用 uv pip install。

输入文件被认为是 pip compile 或 uv export 操作的输出，其中将包含所有传递依赖项。如果文件中不存在传递依赖项，则不会安装它们。如果缺少任何传递依赖项，请使用 --strict 发出警告。

用法

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

参数

SRC_FILE

包含给定 requirements.txt 文件中列出的所有包。

如果提供了 pyproject.toml、setup.py 或 setup.cfg 文件，uv 将提取相关项目的 requirements。

如果提供了 -，则将从 stdin 读取 requirements。

Options (选项)

允许同步空 requirements，这将清除环境中所有包

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

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

可以多次提供。

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

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

也可以使用 UV_INSECURE_HOST 环境变量设置。

--break-system-packages

允许 uv 修改 EXTERNALLY-MANAGED Python 安装。

警告：--break-system-packages 旨在用于持续集成 (CI) 环境中，当安装到由外部包管理器（如 apt）管理的 Python 安装中时。应谨慎使用，因为此类 Python 安装明确建议不要被其他包管理器（如 uv 或 pip）修改。

也可以使用 UV_BREAK_SYSTEM_PACKAGES 环境变量设置。

--build-constraints, --build-constraint, -b build-constraints

在构建源代码分发时，使用给定的 requirements 文件约束构建依赖项。

Constraints 文件是类似于 requirements.txt 的文件，它只控制已安装的 requirement 的版本。但是，在 constraints 文件中包含一个软件包不会触发该软件包的安装。

也可以使用 UV_BUILD_CONSTRAINT 环境变量设置。

--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 构建后端的设置，指定为 KEY=VALUE 对

--constraints, --constraint, -c constraints

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

Constraints 文件是类似于 requirements.txt 的文件，它只控制已安装的 requirement 的版本。但是，在 constraints 文件中包含一个软件包不会触发该软件包的安装。

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

也可以使用 UV_CONSTRAINT 环境变量进行设置。

--default-index default-index

默认包索引的 URL（默认情况下：https://pypi.ac.cn/simple）。

接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。

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

也可以使用 UV_DEFAULT_INDEX 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

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

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

执行一次 dry run，即不实际安装任何东西，而是解析依赖项并打印结果计划

--exclude-newer exclude-newer

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

接受 RFC 3339 时间戳（例如，2006-12-02T02:07:43Z）和您系统配置时区中相同格式的本地日期（例如，2006-12-02）。

也可以使用 UV_EXCLUDE_NEWER 环境变量设置。

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

--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.ac.cn/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 命令进行凭据查找

--link-mode link-mode

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

默认为 macOS 上的 clone（也称为 Copy-on-Write），以及 Linux 和 Windows 上的 hardlink。

也可以使用 UV_LINK_MODE 环境变量设置。

可能的值

clone：将 wheel 中的包克隆（即，写时复制）到 site-packages 目录中
copy：将 wheel 中的包复制到 site-packages 目录中
hardlink：将 wheel 中的包硬链接到 site-packages 目录中
symlink：将 wheel 中的包符号链接到 site-packages 目录中

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

--no-allow-empty-requirements

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

--no-binary no-binary

不要安装预构建的 wheel 包。

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

可以提供多个包。使用 :all: 禁用所有包的二进制文件。使用 :none: 清除先前指定的包。

--no-break-system-packages

不要构建源分发包。

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

--only-binary :all: 的别名。

构建源分发包时禁用隔离。

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

也可以使用 UV_NO_BUILD_ISOLATION 环境变量设置。

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

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

也可以使用 UV_NO_CACHE 环境变量设置。

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

禁用 uv 管理的 Python 版本的使用。

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

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

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

--no-verify-hashes

禁用 requirements 文件中哈希的验证。

默认情况下，uv 将验证 requirements 文件中的任何可用哈希，但不要求所有 requirements 都具有关联的哈希。要强制执行哈希验证，请使用 --require-hashes。

也可以使用 UV_NO_VERIFY_HASHES 环境变量设置。

禁用网络访问。

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

也可以使用 UV_OFFLINE 环境变量设置。

--only-binary only-binary

仅使用预构建的 wheels；不要构建源码发行版。

启用后，解析将不会运行来自给定包的代码。已经构建的源码发行版的缓存 wheels 将被重用，但是需要构建发行版的操作将以错误退出。

可以提供多个包。使用 :all: 禁用所有包的二进制文件。使用 :none: 清除先前指定的包。

--prefix prefix

将包安装到指定目录下的 lib、bin 和其他顶层文件夹中，就像该位置存在虚拟环境一样。

一般来说，更喜欢使用 --python 安装到备用环境中，因为通过 --prefix 安装的脚本和其他工件将引用安装解释器，而不是添加到 --prefix 目录中的任何解释器，从而使其不可移植。

--project project

在给定的项目目录中运行命令。

所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境 (.venv) 也会被发现。

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

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

此设置在 uv pip 界面中使用时无效。

也可以使用 UV_PROJECT 环境变量设置。

--python, -p python

应将包安装到的 Python 解释器。

默认情况下，同步需要虚拟环境。可以提供备用 Python 的路径，但仅建议在持续集成 (CI) 环境中使用，应谨慎使用，因为它可能会修改系统 Python 安装。

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

也可以使用 UV_PYTHON 环境变量设置。

--python-platform python-platform

应为其安装需求的平台。

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

当以 macOS (Darwin) 为目标时，默认最低版本为 12.0。使用 MACOSX_DEPLOYMENT_TARGET 指定不同的最低版本，例如，13.0。

警告：指定后，uv 将选择与目标平台兼容的 wheels；因此，安装的发行版可能与当前平台不兼容。相反，任何从源代码构建的发行版可能与目标平台不兼容，因为它们将为当前平台构建。--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 目标
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 目标
x86_64-unknown-linux-musl：x86_64 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 目标
wasm32-pyodide2024：使用 Pyodide 2024 平台的 wasm32 目标。适用于 Python 3.12

--python-version python-version

requirements 应支持的最低 Python 版本（例如，3.7 或 3.7.9）。

如果省略了补丁版本，则假定为最低补丁版本。例如，3.7 映射到 3.7.0。

--quiet, -q

使用安静输出。

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

刷新所有缓存数据

--refresh-package refresh-package

刷新特定包的缓存数据

--reinstall, --force-reinstall

重新安装所有包，无论它们是否已经安装。暗示 --refresh

--reinstall-package reinstall-package

重新安装特定包，无论它是否已经安装。暗示 --refresh-package

--require-hashes

要求每个 requirement 都有一个匹配的哈希。

默认情况下，uv 将验证 requirements 文件中的任何可用哈希，但不要求所有 requirements 都具有关联的哈希。

当启用 --require-hashes 时，所有 requirement 都必须包含一个或一组哈希，并且所有 requirement 都必须被固定到精确版本（例如，==1.0.0），或者通过直接 URL 指定。

哈希检查模式引入了许多附加约束

不支持 Git 依赖项。 - 不支持可编辑安装。 - 不支持本地依赖项，除非它们指向特定的 wheel (.whl) 或源码存档（.zip、.tar.gz），而不是目录。

也可以使用 UV_REQUIRE_HASHES 环境变量设置。

完成安装后验证 Python 环境，以检测缺少依赖项或其他问题的包

将包安装到系统 Python 环境中。

默认情况下，uv 安装到当前工作目录或任何父目录中的虚拟环境中。 --system 选项指示 uv 改为使用在系统 PATH 中找到的第一个 Python。

警告：--system 旨在用于持续集成 (CI) 环境中，应谨慎使用，因为它可能会修改系统 Python 安装。

也可以使用 UV_SYSTEM_PYTHON 环境变量设置。

--target target

将包安装到指定的目录中，而不是安装到虚拟或系统 Python 环境中。包将安装在目录的顶层

--torch-backend torch-backend

在 PyTorch 生态系统中获取包时使用的后端（例如，cpu、cu126 或 auto）。

设置后，uv 将忽略 PyTorch 生态系统中包的配置索引 URL，而是使用定义的后端。

例如，当设置为 cpu 时，uv 将使用仅 CPU 的 PyTorch 索引；当设置为 cu126 时，uv 将使用 CUDA 12.6 的 PyTorch 索引。

auto 模式将尝试基于当前安装的 CUDA 驱动程序检测合适的 PyTorch 索引。

此选项处于预览状态，可能会在未来的任何版本中更改。

也可以使用 UV_TORCH_BACKEND 环境变量设置。

可能的值

auto：基于操作系统和 CUDA 驱动程序版本选择合适的 PyTorch 索引
cpu：使用仅 CPU 的 PyTorch 索引
cu128：使用 CUDA 12.8 的 PyTorch 索引
cu126：使用 CUDA 12.6 的 PyTorch 索引
cu125：使用 CUDA 12.5 的 PyTorch 索引
cu124：使用 CUDA 12.4 的 PyTorch 索引
cu123：使用 CUDA 12.3 的 PyTorch 索引
cu122：使用 CUDA 12.2 的 PyTorch 索引
cu121：使用 CUDA 12.1 的 PyTorch 索引
cu120：使用 CUDA 12.0 的 PyTorch 索引
cu118：使用 CUDA 11.8 的 PyTorch 索引
cu117：使用 CUDA 11.7 的 PyTorch 索引
cu116：使用 CUDA 11.6 的 PyTorch 索引
cu115：使用 CUDA 11.5 的 PyTorch 索引
cu114：使用 CUDA 11.4 的 PyTorch 索引
cu113：使用 CUDA 11.3 的 PyTorch 索引
cu112：使用 CUDA 11.2 的 PyTorch 索引
cu111：使用 CUDA 11.1 的 PyTorch 索引
cu110：使用 CUDA 11.0 的 PyTorch 索引
cu102：使用 CUDA 10.2 的 PyTorch 索引
cu101：使用 CUDA 10.1 的 PyTorch 索引
cu100：使用 CUDA 10.0 的 PyTorch 索引
cu92：使用 CUDA 9.2 的 PyTorch 索引
cu91：使用 CUDA 9.1 的 PyTorch 索引
cu90：使用 CUDA 9.0 的 PyTorch 索引
cu80：使用 CUDA 8.0 的 PyTorch 索引
rocm6.3：使用 ROCm 6.3 的 PyTorch 索引
rocm6.2.4：使用 ROCm 6.2.4 的 PyTorch 索引
rocm6.2：使用 ROCm 6.2 的 PyTorch 索引
rocm6.1：使用 ROCm 6.1 的 PyTorch 索引
rocm6.0：使用 ROCm 6.0 的 PyTorch 索引
rocm5.7：使用 ROCm 5.7 的 PyTorch 索引
rocm5.6：使用 ROCm 5.6 的 PyTorch 索引
rocm5.5：使用 ROCm 5.5 的 PyTorch 索引
rocm5.4.2：使用 ROCm 5.4.2 的 PyTorch 索引
rocm5.4：使用 ROCm 5.4 的 PyTorch 索引
rocm5.3：使用 ROCm 5.3 的 PyTorch 索引
rocm5.2：使用 ROCm 5.2 的 PyTorch 索引
rocm5.1.1：使用 ROCm 5.1.1 的 PyTorch 索引
rocm4.2：使用 ROCm 4.2 的 PyTorch 索引
rocm4.1：使用 ROCm 4.1 的 PyTorch 索引
rocm4.0.1：使用 ROCm 4.0.1 的 PyTorch 索引
xpu：使用 Intel XPU 的 PyTorch 索引

--verbose, -v

使用详细输出。

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

uv pip install

将软件包安装到环境中

用法

uv pip install [OPTIONS] <PACKAGE|--requirements <REQUIREMENTS>|--editable <EDITABLE>|--group <GROUP>>

参数

PACKAGE

安装所有列出的包。

包的顺序用于确定解析期间的优先级。

Options (选项)

--break-system-packages

包括所有可选依赖项。

仅适用于 pyproject.toml、setup.py 和 setup.cfg 源。

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

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

可以多次提供。

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

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

也可以使用 UV_INSECURE_HOST 环境变量设置。

允许 uv 修改 EXTERNALLY-MANAGED Python 安装。

警告：--break-system-packages 旨在用于持续集成 (CI) 环境中，当安装到由外部包管理器（如 apt）管理的 Python 安装中时。应谨慎使用，因为此类 Python 安装明确建议不要被其他包管理器（如 uv 或 pip）修改。

也可以使用 UV_BREAK_SYSTEM_PACKAGES 环境变量设置。

--build-constraints, --build-constraint, -b build-constraints

在构建源代码分发时，使用给定的 requirements 文件约束构建依赖项。

Constraints 文件是类似于 requirements.txt 的文件，它只控制已安装的 requirement 的版本。但是，在 constraints 文件中包含一个软件包不会触发该软件包的安装。

也可以使用 UV_BUILD_CONSTRAINT 环境变量设置。

--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 构建后端的设置，指定为 KEY=VALUE 对

--constraints, --constraint, -c constraints

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

Constraints 文件是类似于 requirements.txt 的文件，它只控制已安装的 requirement 的版本。但是，在 constraints 文件中包含一个软件包不会触发该软件包的安装。

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

也可以使用 UV_CONSTRAINT 环境变量进行设置。

--default-index default-index

默认包索引的 URL（默认情况下：https://pypi.ac.cn/simple）。

接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。

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

也可以使用 UV_DEFAULT_INDEX 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

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

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

执行一次 dry run，即不实际安装任何东西，而是解析依赖项并打印结果计划

--editable, -e editable

基于提供的本地文件路径安装可编辑包

--exact

执行精确同步，删除多余的包。

默认情况下，安装将进行必要的最小更改以满足 requirements。启用后，uv 将更新环境以完全匹配 requirements，删除 requirements 中未包含的包。

--exclude-newer exclude-newer

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

接受 RFC 3339 时间戳（例如，2006-12-02T02:07:43Z）和您系统配置时区中相同格式的本地日期（例如，2006-12-02）。

也可以使用 UV_EXCLUDE_NEWER 环境变量设置。

--extra extra

包括来自指定 extra 名称的可选依赖项；可以多次提供。

仅适用于 pyproject.toml、setup.py 和 setup.cfg 源。

--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 版本选择每个包的最新支持版本

--group group

从 pyproject.toml 安装指定的依赖项组。

如果未提供路径，则使用工作目录中的 pyproject.toml。

可以多次提供。

--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.ac.cn/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 命令进行凭据查找

--link-mode link-mode

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

默认为 macOS 上的 clone（也称为 Copy-on-Write），以及 Linux 和 Windows 上的 hardlink。

也可以使用 UV_LINK_MODE 环境变量设置。

可能的值

clone：将 wheel 中的包克隆（即，写时复制）到 site-packages 目录中
copy：将 wheel 中的包复制到 site-packages 目录中
hardlink：将 wheel 中的包硬链接到 site-packages 目录中
symlink：将 wheel 中的包符号链接到 site-packages 目录中

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

--no-break-system-packages

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

--no-binary no-binary

不要安装预构建的 wheel 包。

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

可以提供多个包。使用 :all: 禁用所有包的二进制文件。使用 :none: 清除先前指定的包。

不要构建源分发包。

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

--only-binary :all: 的别名。

构建源分发包时禁用隔离。

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

也可以使用 UV_NO_BUILD_ISOLATION 环境变量设置。

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

为特定包构建源分发包时禁用隔离。

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

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

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

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

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

也可以使用 UV_NO_CONFIG 环境变量设置。

--no-deps

忽略包依赖项，而只安装命令行或 requirements 文件中显式列出的那些包

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

禁用 uv 管理的 Python 版本的使用。

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

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

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

--no-verify-hashes

禁用 requirements 文件中哈希的验证。

默认情况下，uv 将验证 requirements 文件中的任何可用哈希，但不要求所有 requirements 都具有关联的哈希。要强制执行哈希验证，请使用 --require-hashes。

也可以使用 UV_NO_VERIFY_HASHES 环境变量设置。

禁用网络访问。

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

也可以使用 UV_OFFLINE 环境变量设置。

--only-binary only-binary

仅使用预构建的 wheels；不要构建源码发行版。

启用后，解析将不会运行来自给定包的代码。已经构建的源码发行版的缓存 wheels 将被重用，但是需要构建发行版的操作将以错误退出。

可以提供多个包。使用 :all: 禁用所有包的二进制文件。使用 :none: 清除先前指定的包。

--overrides, --override overrides

使用给定的 requirements 文件覆盖版本。

Overrides 文件是类似于 requirements.txt 的文件，它强制安装 requirement 的特定版本，而不管任何组成软件包声明的 requirements，也不管这是否被认为是无效的解析。

虽然 constraints 是附加的，因为它们与组成软件包的 requirements 相结合，但 overrides 是绝对的，因为它们完全替换了组成软件包的 requirements。

也可以使用 UV_OVERRIDE 环境变量设置。

--prefix prefix

将包安装到指定目录下的 lib、bin 和其他顶层文件夹中，就像该位置存在虚拟环境一样。

一般来说，更喜欢使用 --python 安装到备用环境中，因为通过 --prefix 安装的脚本和其他工件将引用安装解释器，而不是添加到 --prefix 目录中的任何解释器，从而使其不可移植。

--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 的路径，但仅建议在持续集成 (CI) 环境中使用，应谨慎使用，因为它可能会修改系统 Python 安装。

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

也可以使用 UV_PYTHON 环境变量设置。

--python-platform python-platform

应为其安装需求的平台。

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

当以 macOS (Darwin) 为目标时，默认最低版本为 12.0。使用 MACOSX_DEPLOYMENT_TARGET 指定不同的最低版本，例如，13.0。

警告：指定后，uv 将选择与目标平台兼容的 wheels；因此，安装的发行版可能与当前平台不兼容。相反，任何从源代码构建的发行版可能与目标平台不兼容，因为它们将为当前平台构建。--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 目标
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 目标
x86_64-unknown-linux-musl：x86_64 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 目标
wasm32-pyodide2024：使用 Pyodide 2024 平台的 wasm32 目标。适用于 Python 3.12

--python-version python-version

requirements 应支持的最低 Python 版本（例如，3.7 或 3.7.9）。

如果省略了补丁版本，则假定为最低补丁版本。例如，3.7 映射到 3.7.0。

--quiet, -q

使用安静输出。

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

刷新所有缓存数据

--refresh-package refresh-package

刷新特定包的缓存数据

--reinstall, --force-reinstall

重新安装所有包，无论它们是否已经安装。暗示 --refresh

--reinstall-package reinstall-package

重新安装特定包，无论它是否已经安装。暗示 --refresh-package

--require-hashes

要求每个 requirement 都有一个匹配的哈希。

默认情况下，uv 将验证 requirements 文件中的任何可用哈希，但不要求所有 requirements 都具有关联的哈希。

当启用 --require-hashes 时，所有 requirement 都必须包含一个或一组哈希，并且所有 requirement 都必须被固定到精确版本（例如，==1.0.0），或者通过直接 URL 指定。

哈希检查模式引入了许多附加约束

不支持 Git 依赖项。 - 不支持可编辑安装。 - 不支持本地依赖项，除非它们指向特定的 wheel (.whl) 或源码存档（.zip、.tar.gz），而不是目录。

也可以使用 UV_REQUIRE_HASHES 环境变量设置。

--requirements, --requirement, -r requirements

安装给定 requirements.txt 或 pylock.toml 文件中列出的所有包。

如果提供了 pyproject.toml、setup.py 或 setup.cfg 文件，uv 将提取相关项目的 requirements。

如果提供了 -，则将从 stdin 读取 requirements。

--resolution resolution

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

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

也可以使用 UV_RESOLUTION 环境变量设置。

可能的值

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

完成安装后验证 Python 环境，以检测缺少依赖项或其他问题的包

--break-system-packages

将包安装到系统 Python 环境中。

默认情况下，uv 安装到当前工作目录或任何父目录中的虚拟环境中。 --system 选项指示 uv 改为使用在系统 PATH 中找到的第一个 Python。

警告：--system 旨在用于持续集成 (CI) 环境中，应谨慎使用，因为它可能会修改系统 Python 安装。

也可以使用 UV_SYSTEM_PYTHON 环境变量设置。

--target target

将包安装到指定的目录中，而不是安装到虚拟或系统 Python 环境中。包将安装在目录的顶层

--torch-backend torch-backend

在 PyTorch 生态系统中获取包时使用的后端（例如，cpu、cu126 或 auto）

设置后，uv 将忽略 PyTorch 生态系统中包的配置索引 URL，而是使用定义的后端。

例如，当设置为 cpu 时，uv 将使用仅 CPU 的 PyTorch 索引；当设置为 cu126 时，uv 将使用 CUDA 12.6 的 PyTorch 索引。

auto 模式将尝试基于当前安装的 CUDA 驱动程序检测合适的 PyTorch 索引。

此选项处于预览状态，可能会在未来的任何版本中更改。

也可以使用 UV_TORCH_BACKEND 环境变量设置。

可能的值

auto：基于操作系统和 CUDA 驱动程序版本选择合适的 PyTorch 索引
cpu：使用仅 CPU 的 PyTorch 索引
cu128：使用 CUDA 12.8 的 PyTorch 索引
cu126：使用 CUDA 12.6 的 PyTorch 索引
cu125：使用 CUDA 12.5 的 PyTorch 索引
cu124：使用 CUDA 12.4 的 PyTorch 索引
cu123：使用 CUDA 12.3 的 PyTorch 索引
cu122：使用 CUDA 12.2 的 PyTorch 索引
cu121：使用 CUDA 12.1 的 PyTorch 索引
cu120：使用 CUDA 12.0 的 PyTorch 索引
cu118：使用 CUDA 11.8 的 PyTorch 索引
cu117：使用 CUDA 11.7 的 PyTorch 索引
cu116：使用 CUDA 11.6 的 PyTorch 索引
cu115：使用 CUDA 11.5 的 PyTorch 索引
cu114：使用 CUDA 11.4 的 PyTorch 索引
cu113：使用 CUDA 11.3 的 PyTorch 索引
cu112：使用 CUDA 11.2 的 PyTorch 索引
cu111：使用 CUDA 11.1 的 PyTorch 索引
cu110：使用 CUDA 11.0 的 PyTorch 索引
cu102：使用 CUDA 10.2 的 PyTorch 索引
cu101：使用 CUDA 10.1 的 PyTorch 索引
cu100：使用 CUDA 10.0 的 PyTorch 索引
cu92：使用 CUDA 9.2 的 PyTorch 索引
cu91：使用 CUDA 9.1 的 PyTorch 索引
cu90：使用 CUDA 9.0 的 PyTorch 索引
cu80：使用 CUDA 8.0 的 PyTorch 索引
rocm6.3：使用 ROCm 6.3 的 PyTorch 索引
rocm6.2.4：使用 ROCm 6.2.4 的 PyTorch 索引
rocm6.2：使用 ROCm 6.2 的 PyTorch 索引
rocm6.1：使用 ROCm 6.1 的 PyTorch 索引
rocm6.0：使用 ROCm 6.0 的 PyTorch 索引
rocm5.7：使用 ROCm 5.7 的 PyTorch 索引
rocm5.6：使用 ROCm 5.6 的 PyTorch 索引
rocm5.5：使用 ROCm 5.5 的 PyTorch 索引
rocm5.4.2：使用 ROCm 5.4.2 的 PyTorch 索引
rocm5.4：使用 ROCm 5.4 的 PyTorch 索引
rocm5.3：使用 ROCm 5.3 的 PyTorch 索引
rocm5.2：使用 ROCm 5.2 的 PyTorch 索引
rocm5.1.1：使用 ROCm 5.1.1 的 PyTorch 索引
rocm4.2：使用 ROCm 4.2 的 PyTorch 索引
rocm4.1：使用 ROCm 4.1 的 PyTorch 索引
rocm4.0.1：使用 ROCm 4.0.1 的 PyTorch 索引
xpu：使用 Intel XPU 的 PyTorch 索引

--upgrade, -U

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

--upgrade-package, -P upgrade-package

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

--user

--verbose, -v

使用详细输出。

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

uv pip uninstall

从环境中卸载软件包

用法

uv pip uninstall [OPTIONS] <PACKAGE|--requirements <REQUIREMENTS>>

参数

PACKAGE: 卸载所有列出的包

Options (选项)

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

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

可以多次提供。

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

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

也可以使用 UV_INSECURE_HOST 环境变量设置。

允许 uv 修改 EXTERNALLY-MANAGED Python 安装。

警告：--break-system-packages 旨在用于持续集成 (CI) 环境中，当安装到由外部包管理器（如 apt）管理的 Python 安装中时。应谨慎使用，因为此类 Python 安装明确建议不要被其他包管理器（如 uv 或 pip）修改。

也可以使用 UV_BREAK_SYSTEM_PACKAGES 环境变量设置。

--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：禁用彩色输出

--config-file config-file

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

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

也可以使用 UV_CONFIG_FILE 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

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

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

执行一次 dry run，即不实际卸载任何东西，而是打印结果计划

--help, -h

显示此命令的简明帮助

--keyring-provider keyring-provider

尝试使用 keyring 对远程 requirements 文件进行身份验证。

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

默认为 disabled。

也可以使用 UV_KEYRING_PROVIDER 环境变量设置。

可能的值

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

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

--no-break-system-packages

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

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

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

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

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

也可以使用 UV_NO_CONFIG 环境变量设置。

禁用 uv 管理的 Python 版本的使用。

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

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

禁用网络访问。

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

也可以使用 UV_OFFLINE 环境变量设置。

--prefix prefix

从指定的 --prefix 目录卸载包

--project project

在给定的项目目录中运行命令。

所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境 (.venv) 也会被发现。

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

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

此设置在 uv pip 界面中使用时无效。

也可以使用 UV_PROJECT 环境变量设置。

--python, -p python

应从中卸载包的 Python 解释器。

默认情况下，卸载需要虚拟环境。可以提供备用 Python 的路径，但仅建议在持续集成 (CI) 环境中使用，应谨慎使用，因为它可能会修改系统 Python 安装。

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

也可以使用 UV_PYTHON 环境变量设置。

--quiet, -q

使用安静输出。

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

--requirements, --requirement, -r requirements

卸载给定 requirements 文件中列出的所有包

使用系统 Python 卸载包。

默认情况下，uv 从当前工作目录或任何父目录中的虚拟环境卸载。 --system 选项指示 uv 改为使用在系统 PATH 中找到的第一个 Python。

警告：--system 旨在用于持续集成 (CI) 环境中，应谨慎使用，因为它可能会修改系统 Python 安装。

也可以使用 UV_SYSTEM_PYTHON 环境变量设置。

--target target

从指定的 --target 目录卸载包

--verbose, -v

使用详细输出。

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

uv pip freeze

以 requirements 格式列出环境中安装的软件包

用法

uv pip freeze [OPTIONS]

Options (选项)

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

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

可以多次提供。

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

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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 环境变量设置。

--color color-choice

控制输出中颜色的使用。

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

可能的值

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

--config-file config-file

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

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

也可以使用 UV_CONFIG_FILE 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

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

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

--exclude-editable

从输出中排除任何可编辑包

--help, -h

显示此命令的简明帮助

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

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

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

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

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

也可以使用 UV_NO_CONFIG 环境变量设置。

禁用 uv 管理的 Python 版本的使用。

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

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

禁用网络访问。

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

也可以使用 UV_OFFLINE 环境变量设置。

--path paths

限制为列出包的指定安装路径（可以多次使用）

--project project

在给定的项目目录中运行命令。

所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境 (.venv) 也会被发现。

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

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

此设置在 uv pip 界面中使用时无效。

也可以使用 UV_PROJECT 环境变量设置。

--python, -p python

应为其列出包的 Python 解释器。

默认情况下，uv 列出虚拟环境中的包，但如果没有找到虚拟环境，则将显示系统 Python 环境中的包。

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

也可以使用 UV_PYTHON 环境变量设置。

--quiet, -q

使用安静输出。

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

验证 Python 环境，以检测缺少依赖项和其他问题的包

列出系统 Python 环境中的包。

禁用虚拟环境的发现。

有关 Python 发现的详细信息，请参阅 uv python。

也可以使用 UV_SYSTEM_PYTHON 环境变量设置。

--verbose, -v

使用详细输出。

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

uv pip list

以表格格式列出环境中安装的软件包

用法

uv pip list [OPTIONS]

Options (选项)

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

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

可以多次提供。

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

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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 环境变量设置。

--color color-choice

控制输出中颜色的使用。

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

可能的值

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

--config-file config-file

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

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

也可以使用 UV_CONFIG_FILE 环境变量设置。

--default-index default-index

默认包索引的 URL（默认情况下：https://pypi.ac.cn/simple）。

接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。

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

也可以使用 UV_DEFAULT_INDEX 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

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

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

--editable, -e

仅包含可编辑的项目

--exclude exclude

从输出中排除指定的包

--exclude-editable

从输出中排除任何可编辑包

--exclude-newer exclude-newer

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

接受 RFC 3339 时间戳（例如，2006-12-02T02:07:43Z）和您系统配置时区中相同格式的本地日期（例如，2006-12-02）。

也可以使用 UV_EXCLUDE_NEWER 环境变量设置。

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

--format format

选择输出格式

[默认：columns]

可能的值

columns：以人类可读的表格形式显示包列表
freeze：以类似 pip freeze 的格式显示包列表，每行一个包及其版本
json：以机器可读的 JSON 格式显示包列表

--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.ac.cn/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 命令进行凭据查找

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

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

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

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

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

也可以使用 UV_NO_CONFIG 环境变量设置。

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

禁用 uv 管理的 Python 版本的使用。

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

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

禁用网络访问。

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

也可以使用 UV_OFFLINE 环境变量设置。

--outdated

列出过时的包。

每个包的最新版本将与已安装版本一起显示。最新包将从输出中省略。

--project project

在给定的项目目录中运行命令。

所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境 (.venv) 也会被发现。

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

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

此设置在 uv pip 界面中使用时无效。

也可以使用 UV_PROJECT 环境变量设置。

--python, -p python

应为其列出包的 Python 解释器。

默认情况下，uv 列出虚拟环境中的包，但如果没有找到虚拟环境，则将显示系统 Python 环境中的包。

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

也可以使用 UV_PYTHON 环境变量设置。

--quiet, -q

使用安静输出。

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

验证 Python 环境，以检测缺少依赖项和其他问题的包

列出系统 Python 环境中的包。

禁用虚拟环境的发现。

有关 Python 发现的详细信息，请参阅 uv python。

也可以使用 UV_SYSTEM_PYTHON 环境变量设置。

--verbose, -v

使用详细输出。

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

uv pip show

显示有关一个或多个已安装软件包的信息

用法

uv pip show [OPTIONS] [PACKAGE]...

参数

PACKAGE: 要显示的包

Options (选项)

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

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

可以多次提供。

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

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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 环境变量设置。

--color color-choice

控制输出中颜色的使用。

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

可能的值

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

--config-file config-file

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

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

也可以使用 UV_CONFIG_FILE 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

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

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

--files, -f

显示每个包的已安装文件的完整列表

--help, -h

显示此命令的简明帮助

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

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

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

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

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

也可以使用 UV_NO_CONFIG 环境变量设置。

禁用 uv 管理的 Python 版本的使用。

相反，uv 将在系统上搜索合适的 Python 版本。

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

禁用网络访问。

禁用后，uv 将仅使用本地缓存的数据和本地可用的文件。

也可以使用 UV_OFFLINE 环境变量设置。

--project project

在给定的项目目录中运行命令。

所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境 (.venv) 也会被发现。

其他命令行参数（例如相对路径）将相对于当前工作目录进行解析。

请参阅 --directory 以完全更改工作目录。

此设置在 uv pip 界面中使用时无效。

也可以使用 UV_PROJECT 环境变量设置。

--python, -p python

从中查找包的 Python 解释器。

默认情况下，uv 在虚拟环境中查找包，但如果没有找到虚拟环境，则将查找系统 Python 环境中的包。

有关 Python 发现和支持的请求格式的详细信息，请参阅 uv python。

也可以使用 UV_PYTHON 环境变量设置。

--quiet, -q

使用安静输出。

重复此选项，例如 -qq，将启用静默模式，其中 uv 不会将任何输出写入 stdout。

验证 Python 环境，以检测缺少依赖项和其他问题的包

在系统 Python 环境中显示包。

禁用虚拟环境的发现。

有关 Python 发现的详细信息，请参阅 uv python。

也可以使用 UV_SYSTEM_PYTHON 环境变量设置。

--verbose, -v

使用详细输出。

您可以使用 RUST_LOG 环境变量配置细粒度日志记录。 (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

uv pip tree

显示环境的依赖树

用法

uv pip tree [OPTIONS]

Options (选项)

--allow-insecure-host, --trusted-host allow-insecure-host

允许与主机建立不安全连接。

可以多次提供。

期望接收主机名（例如，localhost）、主机端口对（例如，localhost:8080）或 URL（例如，https://）。

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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 环境变量设置。

--color color-choice

控制输出中颜色的使用。

默认情况下，uv 在写入终端时会自动检测对颜色的支持。

可能的值

auto：仅当输出进入支持的终端或 TTY 时才启用彩色输出
always：无论检测到的环境如何，都启用彩色输出
never：禁用彩色输出

--config-file config-file

用于配置的 uv.toml 文件的路径。

虽然 uv 配置可以包含在 pyproject.toml 文件中，但在此上下文中不允许。

也可以使用 UV_CONFIG_FILE 环境变量设置。

--default-index default-index

默认包索引的 URL（默认情况下：https://pypi.ac.cn/simple）。

接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。

此标志给出的索引的优先级低于通过 --index 标志指定的所有其他索引。

也可以使用 UV_DEFAULT_INDEX 环境变量设置。

--depth, -d depth

依赖项树的最大显示深度

[默认值：255]

--directory directory

在运行命令之前更改为给定的目录。

相对路径以给定目录为基础进行解析。

请参阅 --project 以仅更改项目根目录。

--exclude-newer exclude-newer

将候选包限制为在给定日期之前上传的包。

接受 RFC 3339 时间戳（例如，2006-12-02T02:07:43Z）和您系统配置时区中相同格式的本地日期（例如，2006-12-02）。

也可以使用 UV_EXCLUDE_NEWER 环境变量设置。

--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 环境变量设置。

--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.ac.cn/simple）。

接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。

此标志给出的索引的优先级低于通过 --extra-index-url 标志指定的所有其他索引。

也可以使用 UV_INDEX_URL 环境变量设置。

--invert, --reverse

显示给定软件包的反向依赖项。此标志将反转树并显示依赖于给定软件包的软件包

--keyring-provider keyring-provider

尝试使用 keyring 对索引 URL 进行身份验证。

目前，仅支持 --keyring-provider subprocess，它配置 uv 以使用 keyring CLI 来处理身份验证。

默认为 disabled。

也可以使用 UV_KEYRING_PROVIDER 环境变量设置。

可能的值

disabled：不使用 keyring 进行凭据查找
subprocess：使用 keyring 命令进行凭据查找

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

--no-cache, --no-cache-dir, -n

避免从缓存读取或写入缓存，而是在操作期间使用临时目录

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

通常，在当前目录、父目录或用户配置目录中发现配置文件。

也可以使用 UV_NO_CONFIG 环境变量设置。

--no-dedupe

不要删除重复的依赖项。通常，当一个软件包已经显示了它的依赖项时，进一步的出现将不会重新显示它的依赖项，并且将包含一个 (*) 以指示它已经被显示。此标志将导致这些重复项被重复显示

忽略注册表索引（例如，PyPI），而是依赖于直接 URL 依赖项和通过 --find-links 提供的依赖项

禁用 uv 管理的 Python 版本的使用。

相反，uv 将在系统上搜索合适的 Python 版本。

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

--show-version-specifiers

禁用网络访问。

禁用后，uv 将仅使用本地缓存的数据和本地可用的文件。

也可以使用 UV_OFFLINE 环境变量设置。

--outdated

显示树中每个软件包的最新可用版本

--package package

仅显示指定的软件包

--project project

在给定的项目目录中运行命令。

所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境 (.venv) 也会被发现。

其他命令行参数（例如相对路径）将相对于当前工作目录进行解析。

请参阅 --directory 以完全更改工作目录。

此设置在 uv pip 界面中使用时无效。

也可以使用 UV_PROJECT 环境变量设置。

--prune prune

从依赖项树的显示中修剪给定的软件包

--python, -p python

应为其列出包的 Python 解释器。

默认情况下，uv 列出虚拟环境中的包，但如果没有找到虚拟环境，则将显示系统 Python 环境中的包。

有关 Python 发现和支持的请求格式的详细信息，请参阅 uv python。

也可以使用 UV_PYTHON 环境变量设置。

--quiet, -q

使用安静输出。

重复此选项，例如 -qq，将启用静默模式，其中 uv 不会将任何输出写入 stdout。

显示施加在每个包上的版本约束

验证 Python 环境，以检测缺少依赖项和其他问题的包

列出系统 Python 环境中的包。

禁用虚拟环境的发现。

有关 Python 发现的详细信息，请参阅 uv python。

也可以使用 UV_SYSTEM_PYTHON 环境变量设置。

--verbose, -v

使用详细输出。

您可以使用 RUST_LOG 环境变量配置细粒度日志记录。 (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

uv pip check

验证已安装的软件包是否具有兼容的依赖项

用法

uv pip check [OPTIONS]

Options (选项)

--allow-insecure-host, --trusted-host allow-insecure-host

允许与主机建立不安全连接。

可以多次提供。

期望接收主机名（例如，localhost）、主机端口对（例如，localhost:8080）或 URL（例如，https://）。

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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 环境变量设置。

--color color-choice

控制输出中颜色的使用。

默认情况下，uv 在写入终端时会自动检测对颜色的支持。

可能的值

auto：仅当输出进入支持的终端或 TTY 时才启用彩色输出
always：无论检测到的环境如何，都启用彩色输出
never：禁用彩色输出

--config-file config-file

用于配置的 uv.toml 文件的路径。

虽然 uv 配置可以包含在 pyproject.toml 文件中，但在此上下文中不允许。

也可以使用 UV_CONFIG_FILE 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

相对路径以给定目录为基础进行解析。

请参阅 --project 以仅更改项目根目录。

--help, -h

显示此命令的简明帮助

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

--no-cache, --no-cache-dir, -n

避免从缓存读取或写入缓存，而是在操作期间使用临时目录

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

通常，在当前目录、父目录或用户配置目录中发现配置文件。

也可以使用 UV_NO_CONFIG 环境变量设置。

禁用 uv 管理的 Python 版本的使用。

相反，uv 将在系统上搜索合适的 Python 版本。

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

禁用网络访问。

禁用后，uv 将仅使用本地缓存的数据和本地可用的文件。

也可以使用 UV_OFFLINE 环境变量设置。

--project project

在给定的项目目录中运行命令。

所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境 (.venv) 也会被发现。

其他命令行参数（例如相对路径）将相对于当前工作目录进行解析。

请参阅 --directory 以完全更改工作目录。

此设置在 uv pip 界面中使用时无效。

也可以使用 UV_PROJECT 环境变量设置。

--python, -p python

应为其检查包的 Python 解释器。

默认情况下，uv 检查虚拟环境中的包，但如果没有找到虚拟环境，则将检查系统 Python 环境中的包。

有关 Python 发现和支持的请求格式的详细信息，请参阅 uv python。

也可以使用 UV_PYTHON 环境变量设置。

--quiet, -q

使用安静输出。

重复此选项，例如 -qq，将启用静默模式，其中 uv 不会将任何输出写入 stdout。

检查系统 Python 环境中的包。

禁用虚拟环境的发现。

有关 Python 发现的详细信息，请参阅 uv python。

也可以使用 UV_SYSTEM_PYTHON 环境变量设置。

--verbose, -v

使用详细输出。

您可以使用 RUST_LOG 环境变量配置细粒度日志记录。 (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

uv venv

创建一个虚拟环境。

默认情况下，在工作目录中创建一个名为 .venv 的虚拟环境。可以通过位置提供备用路径。

如果在项目中，可以使用 UV_PROJECT_ENVIRONMENT 环境变量更改默认环境名称；这仅适用于从项目根目录运行时。

如果目标路径已存在虚拟环境，它将被移除，并创建一个新的空虚拟环境。

当使用 uv 时，无需激活虚拟环境。uv 将在工作目录或任何父目录中查找虚拟环境（名为 .venv）。

用法

uv venv [OPTIONS] [PATH]

参数

PATH

要创建的虚拟环境的路径。

默认为工作目录中的 .venv。

相对路径会根据工作目录解析。

Options (选项)

--allow-existing

保留目标路径下的任何现有文件或目录。

默认情况下，如果给定的路径非空，uv venv 将会报错退出。--allow-existing 选项会写入给定的路径，而不管其内容如何，且不会事先清空它。

警告：如果现有虚拟环境和新创建的虚拟环境链接到不同的 Python 解释器，此选项可能会导致意外行为。

--allow-insecure-host, --trusted-host allow-insecure-host

允许与主机建立不安全连接。

可以多次提供。

期望接收主机名（例如，localhost）、主机端口对（例如，localhost:8080）或 URL（例如，https://）。

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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 环境变量设置。

--clear, -c

移除目标路径下的任何现有文件或目录。

默认情况下，如果给定的路径非空，uv venv 将会报错退出。--clear 选项会在创建新的虚拟环境之前清空非空路径。

也可以使用 UV_VENV_CLEAR 环境变量进行设置。

--color color-choice

控制输出中颜色的使用。

默认情况下，uv 在写入终端时会自动检测对颜色的支持。

可能的值

auto：仅当输出进入支持的终端或 TTY 时才启用彩色输出
always：无论检测到的环境如何，都启用彩色输出
never：禁用彩色输出

--config-file config-file

用于配置的 uv.toml 文件的路径。

虽然 uv 配置可以包含在 pyproject.toml 文件中，但在此上下文中不允许。

也可以使用 UV_CONFIG_FILE 环境变量设置。

--default-index default-index

默认包索引的 URL（默认情况下：https://pypi.ac.cn/simple）。

接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。

此标志给出的索引的优先级低于通过 --index 标志指定的所有其他索引。

也可以使用 UV_DEFAULT_INDEX 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

相对路径以给定目录为基础进行解析。

请参阅 --project 以仅更改项目根目录。

--exclude-newer exclude-newer

将候选包限制为在给定日期之前上传的包。

接受 RFC 3339 时间戳（例如，2006-12-02T02:07:43Z）和您系统配置时区中相同格式的本地日期（例如，2006-12-02）。

也可以使用 UV_EXCLUDE_NEWER 环境变量设置。

--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 环境变量设置。

--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.ac.cn/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 命令进行凭据查找

--link-mode link-mode

从全局缓存安装包时使用的方法。

此选项仅用于安装种子包。

默认为 macOS 上的 clone（也称为 Copy-on-Write），以及 Linux 和 Windows 上的 hardlink。

也可以使用 UV_LINK_MODE 环境变量设置。

可能的值

clone：将 wheel 中的包克隆（即，写时复制）到 site-packages 目录中
copy：将 wheel 中的包复制到 site-packages 目录中
hardlink：将 wheel 中的包硬链接到 site-packages 目录中
symlink：将 wheel 中的包符号链接到 site-packages 目录中

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

--no-cache, --no-cache-dir, -n

避免从缓存读取或写入缓存，而是在操作期间使用临时目录

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

通常，在当前目录、父目录或用户配置目录中发现配置文件。

也可以使用 UV_NO_CONFIG 环境变量设置。

忽略注册表索引（例如，PyPI），而是依赖于直接 URL 依赖项和通过 --find-links 提供的依赖项

禁用 uv 管理的 Python 版本的使用。

相反，uv 将在系统上搜索合适的 Python 版本。

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

--no-project, --no-workspace

避免发现项目或工作区。

默认情况下，uv 会在当前目录或任何父目录中搜索项目，以确定虚拟环境的默认路径，并检查 Python 版本约束（如果有）。

禁用 Python 的自动下载。

禁用网络访问。

禁用后，uv 将仅使用本地缓存的数据和本地可用的文件。

也可以使用 UV_OFFLINE 环境变量设置。

--project project

在给定的项目目录中运行命令。

所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境 (.venv) 也会被发现。

其他命令行参数（例如相对路径）将相对于当前工作目录进行解析。

请参阅 --directory 以完全更改工作目录。

此设置在 uv pip 界面中使用时无效。

也可以使用 UV_PROJECT 环境变量设置。

--prompt prompt

为虚拟环境提供一个备选的提示符前缀。

默认情况下，提示符取决于是否为 uv venv 提供了路径。如果提供了路径（例如，uv venv project），则提示符设置为目录名。如果未提供路径（uv venv），则提示符设置为当前目录的名称。

如果提供了“.”，则无论是否为 uv venv 提供了路径，都将使用当前目录名。

--python, -p python

用于虚拟环境的 Python 解释器。

在创建虚拟环境期间，uv 不会在虚拟环境中查找 Python 解释器。

有关 Python 发现和支持的请求格式的详细信息，请参阅 uv python。

也可以使用 UV_PYTHON 环境变量设置。

--quiet, -q

使用安静输出。

重复此选项，例如 -qq，将启用静默模式，其中 uv 不会将任何输出写入 stdout。

--system-site-packages

刷新所有缓存数据

--refresh-package refresh-package

刷新特定包的缓存数据

--relocatable

使虚拟环境可重定位。

可重定位的虚拟环境可以移动和重新分发，而不会使其关联的入口点和激活脚本失效。

请注意，这只能保证标准的 console_scripts 和 gui_scripts。如果其他脚本附带通用的 #!python[w] shebang，则可能会进行调整，而二进制文件将保持不变。

由于使环境可重定位（通过写入相对路径而不是绝对路径），入口点和脚本本身将不可重定位。换句话说，将这些入口点和脚本复制到环境之外的位置将不起作用，因为它们引用的是相对于环境本身的路径。

--seed

将种子包（一个或多个：pip、setuptools 和 wheel）安装到虚拟环境中。

请注意，setuptools 和 wheel 不包含在 Python 3.12+ 环境中。

也可以使用 UV_VENV_SEED 环境变量进行设置。

允许虚拟环境访问系统 site packages 目录。

与 pip 不同，当使用 --system-site-packages 创建虚拟环境时，uv 在运行 uv pip list 或 uv pip install 等命令时不会考虑系统 site packages。--system-site-packages 标志将使虚拟环境在运行时访问系统 site packages 目录，但不会影响 uv 命令的行为。

--verbose, -v

使用详细输出。

您可以使用 RUST_LOG 环境变量配置细粒度日志记录。 (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

uv build

将 Python 包构建为源代码发行版和 wheel。

uv build 接受目录或源代码发行版的路径，默认为当前工作目录。

默认情况下，如果传递的是目录，uv build 将从源目录构建一个源代码发行版（“sdist”），并从源代码发行版构建一个二进制发行版（“wheel”）。

uv build --sdist 可用于仅构建源代码发行版，uv build --wheel 可用于仅构建二进制发行版，uv build --sdist --wheel 可用于从源代码构建两个发行版。

如果传递的是源代码发行版，uv build --wheel 将从源代码发行版构建一个 wheel。

用法

uv build [OPTIONS] [SRC]

参数

SRC

从中构建发行版的目录，或是要构建为 wheel 的源代码发行版存档。

默认为当前工作目录。

Options (选项)

--all-packages, --all

构建工作区中的所有包。

将从提供的源目录或当前目录（如果未提供源目录）中发现工作区。

如果工作区成员不存在，uv 将退出并显示错误。

--allow-insecure-host, --trusted-host allow-insecure-host

允许与主机建立不安全连接。

可以多次提供。

期望接收主机名（例如，localhost）、主机端口对（例如，localhost:8080）或 URL（例如，https://）。

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您受到 MITM 攻击。

也可以使用 UV_INSECURE_HOST 环境变量设置。

--build-constraints, --build-constraint, -b build-constraints

在构建发行版时，使用给定的 requirements 文件约束构建依赖项。

约束文件是类似于 requirements.txt 的文件，它们只控制安装的构建依赖项的版本。但是，在约束文件中包含一个包不会单独触发该包的包含。

也可以使用 UV_BUILD_CONSTRAINT 环境变量设置。

--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：禁用彩色输出

--config-file config-file

用于配置的 uv.toml 文件的路径。

虽然 uv 配置可以包含在 pyproject.toml 文件中，但在此上下文中不允许。

也可以使用 UV_CONFIG_FILE 环境变量设置。

--config-setting, --config-settings, -C config-setting

传递给 PEP 517 构建后端的设置，指定为 KEY=VALUE 对

--default-index default-index

默认包索引的 URL（默认情况下：https://pypi.ac.cn/simple）。

接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。

此标志给出的索引的优先级低于通过 --index 标志指定的所有其他索引。

也可以使用 UV_DEFAULT_INDEX 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

相对路径以给定目录为基础进行解析。

请参阅 --project 以仅更改项目根目录。

--exclude-newer exclude-newer

将候选包限制为在给定日期之前上传的包。

接受 RFC 3339 时间戳（例如，2006-12-02T02:07:43Z）和您系统配置时区中相同格式的本地日期（例如，2006-12-02）。

也可以使用 UV_EXCLUDE_NEWER 环境变量设置。

--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 环境变量设置。

--force-pep517

始终通过 PEP 517 构建，不要对 uv 构建后端使用快速路径。

默认情况下，uv 不会为使用 uv 构建后端的包创建 PEP 517 构建环境，而是使用直接调用构建后端的快速路径。此选项强制始终使用 PEP 517。

--fork-strategy fork-strategy

跨 Python 版本和平台选择给定包的多个版本时使用的策略。

默认情况下，uv 将优化为为每个支持的 Python 版本 (requires-python) 选择每个包的最新版本，同时最大限度地减少跨平台选择的版本数量。

在 fewest 下，uv 将最大限度地减少每个包选择的版本数量，优先选择与更广泛的支持的 Python 版本或平台兼容的旧版本。

也可以使用 UV_FORK_STRATEGY 环境变量设置。

可能的值

fewest：优化为选择每个包的最少版本数。如果旧版本与更广泛的支持的 Python 版本或平台兼容，则可能会优先选择旧版本
requires-python：优化为为每个支持的 Python 版本选择每个包的最新支持版本

--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.ac.cn/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 命令进行凭据查找

--link-mode link-mode

从全局缓存安装包时使用的方法。

此选项仅在构建源代码分发时使用。

默认为 macOS 上的 clone（也称为 Copy-on-Write），以及 Linux 和 Windows 上的 hardlink。

也可以使用 UV_LINK_MODE 环境变量设置。

可能的值

clone：将 wheel 中的包克隆（即，写时复制）到 site-packages 目录中
copy：将 wheel 中的包复制到 site-packages 目录中
hardlink：将 wheel 中的包硬链接到 site-packages 目录中
symlink：将 wheel 中的包符号链接到 site-packages 目录中

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

不要安装预构建的 wheel 包。

给定的包将从源代码构建和安装。如果可用，解析器仍将使用预构建的 wheel 包来提取包元数据。

也可以使用 UV_NO_BINARY 环境变量设置。

--no-binary-package no-binary-package

不要安装特定包的预构建 wheel 包

也可以使用 UV_NO_BINARY_PACKAGE 环境变量设置。

不要构建源分发包。

启用后，解析将不会运行任意 Python 代码。已经构建的源分发包的缓存 wheel 包将被重用，但是需要构建分发包的操作将退出并显示错误。

也可以使用 UV_NO_BUILD 环境变量设置。

构建源分发包时禁用隔离。

假定 PEP 518 指定的构建依赖项已经安装。

也可以使用 UV_NO_BUILD_ISOLATION 环境变量设置。

--no-build-isolation-package no-build-isolation-package

为特定包构建源分发包时禁用隔离。

假定 PEP 518 指定的包的构建依赖项已经安装。

--no-build-logs

隐藏构建后端的日志

--no-build-package no-build-package

不要构建特定包的源分发包

也可以使用 UV_NO_BUILD_PACKAGE 环境变量设置。

--no-cache, --no-cache-dir, -n

避免从缓存读取或写入缓存，而是在操作期间使用临时目录

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

通常，在当前目录、父目录或用户配置目录中发现配置文件。

也可以使用 UV_NO_CONFIG 环境变量设置。

忽略注册表索引（例如，PyPI），而是依赖于直接 URL 依赖项和通过 --find-links 提供的依赖项

禁用 uv 管理的 Python 版本的使用。

相反，uv 将在系统上搜索合适的 Python 版本。

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

解析依赖项时忽略 tool.uv.sources 表。用于锁定符合标准、可发布包元数据的依赖项，而不是使用任何工作区、Git、URL 或本地路径源

--no-verify-hashes

禁用 requirements 文件中哈希的验证。

默认情况下，uv 将验证 requirements 文件中的任何可用哈希，但不要求所有 requirements 都具有关联的哈希。要强制执行哈希验证，请使用 --require-hashes。

也可以使用 UV_NO_VERIFY_HASHES 环境变量设置。

禁用网络访问。

禁用后，uv 将仅使用本地缓存的数据和本地可用的文件。

也可以使用 UV_OFFLINE 环境变量设置。

--out-dir, -o out-dir

应将发行版写入的输出目录。

默认为源目录中的 dist 子目录，或包含源代码发行版存档的目录。

--package package

构建工作区中的特定包。

将从提供的源目录或当前目录（如果未提供源目录）中发现工作区。

如果工作区成员不存在，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 解释器。

默认情况下，构建在隔离的虚拟环境中执行。发现的解释器将用于创建这些环境，并将根据平台以符号链接或复制的方式链接或复制。

请参阅 uv python 以查看支持的请求格式。

也可以使用 UV_PYTHON 环境变量设置。

--quiet, -q

使用安静输出。

重复此选项，例如 -qq，将启用静默模式，其中 uv 不会将任何输出写入 stdout。

刷新所有缓存数据

--refresh-package refresh-package

刷新特定包的缓存数据

--require-hashes

要求每个 requirement 都有一个匹配的哈希。

默认情况下，uv 将验证 requirements 文件中的任何可用哈希，但不要求所有 requirements 都具有关联的哈希。

当启用 --require-hashes 时，所有 requirement 都必须包含一个或一组哈希，并且所有 requirement 都必须被固定到精确版本（例如，==1.0.0），或者通过直接 URL 指定。

哈希检查模式引入了许多附加约束

不支持 Git 依赖项。 - 不支持可编辑安装。 - 不支持本地依赖项，除非它们指向特定的 wheel (.whl) 或源码存档（.zip、.tar.gz），而不是目录。

也可以使用 UV_REQUIRE_HASHES 环境变量设置。

--resolution resolution

在给定包要求的不同兼容版本之间进行选择时使用的策略。

默认情况下，uv 将使用每个包的最新兼容版本 (highest)。

也可以使用 UV_RESOLUTION 环境变量设置。

可能的值

highest：解析每个包的最高兼容版本
lowest：解析每个包的最低兼容版本
lowest-direct：解析任何直接依赖项的最低兼容版本，以及任何传递依赖项的最高兼容版本

--sdist

从给定目录构建源代码发行版（“sdist”）

--upgrade, -U

允许包升级，忽略任何现有输出文件中的固定版本。暗示 --refresh

--upgrade-package, -P upgrade-package

允许特定包的升级，忽略任何现有输出文件中的固定版本。暗示 --refresh-package

--verbose, -v

使用详细输出。

您可以使用 RUST_LOG 环境变量配置细粒度日志记录。 (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

--wheel

从给定目录构建二进制发行版（“wheel”）

uv publish

将分发包上传到索引

用法

uv publish [OPTIONS] [FILES]...

参数

FILES

要上传的文件的路径。接受 glob 表达式。

默认为 dist 目录。仅选择 wheel 和源代码发行版，同时忽略其他文件。

Options (选项)

--allow-insecure-host, --trusted-host allow-insecure-host

允许与主机建立不安全连接。

可以多次提供。

期望接收主机名（例如，localhost）、主机端口对（例如，localhost:8080）或 URL（例如，https://）。

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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-url check-url

检查索引 URL 中是否存在要跳过重复上传的现有文件。

此选项允许重试仅在上传了部分文件而不是全部文件后失败的发布，并处理由于同一文件的并行上传而导致的错误。

上传之前，会检查索引。如果索引中已存在完全相同的文件，则不会上传该文件。如果在上传过程中发生错误，则会再次检查索引，以处理在并行上传中两次上传相同文件的情况。

确切的行为会因索引而异。上传到 PyPI 时，即使没有 --check-url，上传相同的文件也会成功，而大多数其他索引会出错。

索引必须提供支持的哈希值之一（SHA-256、SHA-384 或 SHA-512）。

也可以使用 UV_PUBLISH_CHECK_URL 环境变量进行设置。

--color color-choice

控制输出中颜色的使用。

默认情况下，uv 在写入终端时会自动检测对颜色的支持。

可能的值

auto：仅当输出进入支持的终端或 TTY 时才启用彩色输出
always：无论检测到的环境如何，都启用彩色输出
never：禁用彩色输出

--config-file config-file

用于配置的 uv.toml 文件的路径。

虽然 uv 配置可以包含在 pyproject.toml 文件中，但在此上下文中不允许。

也可以使用 UV_CONFIG_FILE 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

相对路径以给定目录为基础进行解析。

请参阅 --project 以仅更改项目根目录。

--help, -h

显示此命令的简明帮助

--index index

配置中用于发布的索引的名称。

索引必须具有 publish-url 设置，例如

[[tool.uv.index]]
name = "pypi"
url = "https://pypi.ac.cn/simple"
publish-url = "https://upload.pypi.org/legacy/"

索引 url 将用于检查要跳过重复上传的现有文件。

使用这些设置，以下两个调用是等效的

uv publish --index pypi
uv publish --publish-url https://upload.pypi.org/legacy/ --check-url https://pypi.ac.cn/simple

也可以使用 UV_PUBLISH_INDEX 环境变量进行设置。

--keyring-provider keyring-provider

尝试使用 keyring 对远程 requirements 文件进行身份验证。

目前，仅支持 --keyring-provider subprocess，它配置 uv 以使用 keyring CLI 来处理身份验证。

默认为 disabled。

也可以使用 UV_KEYRING_PROVIDER 环境变量设置。

可能的值

disabled：不使用 keyring 进行凭据查找
subprocess：使用 keyring 命令进行凭据查找

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

--no-cache, --no-cache-dir, -n

避免从缓存读取或写入缓存，而是在操作期间使用临时目录

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

通常，在当前目录、父目录或用户配置目录中发现配置文件。

也可以使用 UV_NO_CONFIG 环境变量设置。

禁用 uv 管理的 Python 版本的使用。

相反，uv 将在系统上搜索合适的 Python 版本。

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

禁用网络访问。

禁用后，uv 将仅使用本地缓存的数据和本地可用的文件。

也可以使用 UV_OFFLINE 环境变量设置。

--password, -p password

上传的密码

也可以使用 UV_PUBLISH_PASSWORD 环境变量进行设置。

--project project

在给定的项目目录中运行命令。

所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境 (.venv) 也会被发现。

其他命令行参数（例如相对路径）将相对于当前工作目录进行解析。

请参阅 --directory 以完全更改工作目录。

此设置在 uv pip 界面中使用时无效。

也可以使用 UV_PROJECT 环境变量设置。

--publish-url publish-url

上传端点的 URL（不是索引 URL）。

请注意，索引访问（例如 https:://.../simple）和索引上传通常有不同的 URL。

默认为 PyPI 的发布 URL (https://upload.pypi.org/legacy/)。

也可以使用 UV_PUBLISH_URL 环境变量进行设置。

--quiet, -q

使用安静输出。

重复此选项，例如 -qq，将启用静默模式，其中 uv 不会将任何输出写入 stdout。

--token, -t token

上传的令牌。

使用令牌等同于将 __token__ 作为 --username 传递，并将令牌作为 --password 密码传递。

也可以使用 UV_PUBLISH_TOKEN 环境变量进行设置。

--trusted-publishing trusted-publishing

配置使用 GitHub Actions 进行可信发布。

默认情况下，uv 在 GitHub Actions 中运行时会检查可信发布，但如果未配置或工作流没有足够的权限（例如，来自 fork 的拉取请求），则会忽略它。

可能的值

automatic：当我们在 GitHub Actions 中时尝试可信发布，如果失败则继续
always
never

--username, -u username

上传的用户名

也可以使用 UV_PUBLISH_USERNAME 环境变量进行设置。

--verbose, -v

使用详细输出。

您可以使用 RUST_LOG 环境变量配置细粒度日志记录。 (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

uv cache

管理 uv 的缓存

用法

uv cache [OPTIONS] <COMMAND>

命令

uv cache clean: 清除缓存，删除所有条目或与特定包链接的条目
uv cache prune: 从缓存中修剪所有无法访问的对象
uv cache dir: 显示缓存目录

uv cache clean

清除缓存，删除所有条目或与特定包链接的条目

用法

uv cache clean [OPTIONS] [PACKAGE]...

参数

PACKAGE: 要从缓存中删除的包

Options (选项)

--allow-insecure-host, --trusted-host allow-insecure-host

允许与主机建立不安全连接。

可以多次提供。

期望接收主机名（例如，localhost）、主机端口对（例如，localhost:8080）或 URL（例如，https://）。

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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 环境变量设置。

--color color-choice

控制输出中颜色的使用。

默认情况下，uv 在写入终端时会自动检测对颜色的支持。

可能的值

auto：仅当输出进入支持的终端或 TTY 时才启用彩色输出
always：无论检测到的环境如何，都启用彩色输出
never：禁用彩色输出

--config-file config-file

用于配置的 uv.toml 文件的路径。

虽然 uv 配置可以包含在 pyproject.toml 文件中，但在此上下文中不允许。

也可以使用 UV_CONFIG_FILE 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

相对路径以给定目录为基础进行解析。

请参阅 --project 以仅更改项目根目录。

--help, -h

显示此命令的简明帮助

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

--no-cache, --no-cache-dir, -n

避免从缓存读取或写入缓存，而是在操作期间使用临时目录

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

通常，在当前目录、父目录或用户配置目录中发现配置文件。

也可以使用 UV_NO_CONFIG 环境变量设置。

禁用 uv 管理的 Python 版本的使用。

相反，uv 将在系统上搜索合适的 Python 版本。

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

禁用网络访问。

禁用后，uv 将仅使用本地缓存的数据和本地可用的文件。

也可以使用 UV_OFFLINE 环境变量设置。

--project project

在给定的项目目录中运行命令。

所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境 (.venv) 也会被发现。

其他命令行参数（例如相对路径）将相对于当前工作目录进行解析。

请参阅 --directory 以完全更改工作目录。

此设置在 uv pip 界面中使用时无效。

也可以使用 UV_PROJECT 环境变量设置。

--quiet, -q

使用安静输出。

重复此选项，例如 -qq，将启用静默模式，其中 uv 不会将任何输出写入 stdout。

--verbose, -v

使用详细输出。

您可以使用 RUST_LOG 环境变量配置细粒度日志记录。 (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

uv cache prune

从缓存中修剪所有无法访问的对象

用法

uv cache prune [OPTIONS]

Options (选项)

--allow-insecure-host, --trusted-host allow-insecure-host

允许与主机建立不安全连接。

可以多次提供。

期望接收主机名（例如，localhost）、主机端口对（例如，localhost:8080）或 URL（例如，https://）。

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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 环境变量设置。

--ci

优化持续集成环境（如 GitHub Actions）中持久性的缓存。

默认情况下，uv 会缓存从源代码构建的 wheel 和直接下载的预构建 wheel，以实现高性能的包安装。但是，在某些情况下，持久化预构建 wheel 可能是不希望的。例如，在 GitHub Actions 中，从缓存中省略预构建 wheel 并在每次运行时重新下载它们会更快。但是，缓存从源代码构建的 wheel 通常确实更快，因为 wheel 构建过程可能很昂贵，尤其是对于扩展模块。

在 --ci 模式下，uv 将从缓存中修剪任何预构建的 wheel，但保留任何从源代码构建的 wheel。

--color color-choice

控制输出中颜色的使用。

默认情况下，uv 在写入终端时会自动检测对颜色的支持。

可能的值

auto：仅当输出进入支持的终端或 TTY 时才启用彩色输出
always：无论检测到的环境如何，都启用彩色输出
never：禁用彩色输出

--config-file config-file

用于配置的 uv.toml 文件的路径。

虽然 uv 配置可以包含在 pyproject.toml 文件中，但在此上下文中不允许。

也可以使用 UV_CONFIG_FILE 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

相对路径以给定目录为基础进行解析。

请参阅 --project 以仅更改项目根目录。

--help, -h

显示此命令的简明帮助

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

--no-cache, --no-cache-dir, -n

避免从缓存读取或写入缓存，而是在操作期间使用临时目录

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

通常，在当前目录、父目录或用户配置目录中发现配置文件。

也可以使用 UV_NO_CONFIG 环境变量设置。

禁用 uv 管理的 Python 版本的使用。

相反，uv 将在系统上搜索合适的 Python 版本。

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

禁用网络访问。

禁用后，uv 将仅使用本地缓存的数据和本地可用的文件。

也可以使用 UV_OFFLINE 环境变量设置。

--project project

在给定的项目目录中运行命令。

所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境 (.venv) 也会被发现。

其他命令行参数（例如相对路径）将相对于当前工作目录进行解析。

请参阅 --directory 以完全更改工作目录。

此设置在 uv pip 界面中使用时无效。

也可以使用 UV_PROJECT 环境变量设置。

--quiet, -q

使用安静输出。

重复此选项，例如 -qq，将启用静默模式，其中 uv 不会将任何输出写入 stdout。

--verbose, -v

使用详细输出。

您可以使用 RUST_LOG 环境变量配置细粒度日志记录。 (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

uv cache dir

显示缓存目录。

默认情况下，缓存存储在 Unix 上的 $XDG_CACHE_HOME/uv 或 $HOME/.cache/uv 中，在 Windows 上的 %LOCALAPPDATA%\uv\cache 中。

使用 --no-cache 时，缓存存储在临时目录中，并在进程退出时丢弃。

可以通过 cache-dir 设置、--cache-dir 选项或 $UV_CACHE_DIR 环境变量指定备用缓存目录。

请注意，对于性能而言，缓存目录与 uv 运行的 Python 环境位于同一文件系统上非常重要。

用法

uv cache dir [OPTIONS]

Options (选项)

--allow-insecure-host, --trusted-host allow-insecure-host

允许与主机建立不安全连接。

可以多次提供。

期望接收主机名（例如，localhost）、主机端口对（例如，localhost:8080）或 URL（例如，https://）。

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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 环境变量设置。

--color color-choice

控制输出中颜色的使用。

默认情况下，uv 在写入终端时会自动检测对颜色的支持。

可能的值

auto：仅当输出进入支持的终端或 TTY 时才启用彩色输出
always：无论检测到的环境如何，都启用彩色输出
never：禁用彩色输出

--config-file config-file

用于配置的 uv.toml 文件的路径。

虽然 uv 配置可以包含在 pyproject.toml 文件中，但在此上下文中不允许。

也可以使用 UV_CONFIG_FILE 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

相对路径以给定目录为基础进行解析。

请参阅 --project 以仅更改项目根目录。

--help, -h

显示此命令的简明帮助

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

--no-cache, --no-cache-dir, -n

避免从缓存读取或写入缓存，而是在操作期间使用临时目录

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

通常，在当前目录、父目录或用户配置目录中发现配置文件。

也可以使用 UV_NO_CONFIG 环境变量设置。

禁用 uv 管理的 Python 版本的使用。

相反，uv 将在系统上搜索合适的 Python 版本。

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

禁用网络访问。

禁用后，uv 将仅使用本地缓存的数据和本地可用的文件。

也可以使用 UV_OFFLINE 环境变量设置。

--project project

在给定的项目目录中运行命令。

所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境 (.venv) 也会被发现。

其他命令行参数（例如相对路径）将相对于当前工作目录进行解析。

请参阅 --directory 以完全更改工作目录。

此设置在 uv pip 界面中使用时无效。

也可以使用 UV_PROJECT 环境变量设置。

--quiet, -q

使用安静输出。

重复此选项，例如 -qq，将启用静默模式，其中 uv 不会将任何输出写入 stdout。

--verbose, -v

使用详细输出。

您可以使用 RUST_LOG 环境变量配置细粒度日志记录。 (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

uv self

管理 uv 可执行文件

用法

uv self [OPTIONS] <COMMAND>

命令

uv self update: 更新 uv
uv self version: 显示 uv 的版本

uv self update

更新 uv

用法

uv self update [OPTIONS] [TARGET_VERSION]

参数

TARGET_VERSION: 更新到指定的版本。如果未提供，uv 将更新到最新版本

Options (选项)

--allow-insecure-host, --trusted-host allow-insecure-host

允许与主机建立不安全连接。

可以多次提供。

期望接收主机名（例如，localhost）、主机端口对（例如，localhost:8080）或 URL（例如，https://）。

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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 环境变量设置。

--color color-choice

控制输出中颜色的使用。

默认情况下，uv 在写入终端时会自动检测对颜色的支持。

可能的值

auto：仅当输出进入支持的终端或 TTY 时才启用彩色输出
always：无论检测到的环境如何，都启用彩色输出
never：禁用彩色输出

--config-file config-file

用于配置的 uv.toml 文件的路径。

虽然 uv 配置可以包含在 pyproject.toml 文件中，但在此上下文中不允许。

也可以使用 UV_CONFIG_FILE 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

相对路径以给定目录为基础进行解析。

请参阅 --project 以仅更改项目根目录。

在不执行更新的情况下运行

--help, -h

显示此命令的简明帮助

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

--no-cache, --no-cache-dir, -n

避免从缓存读取或写入缓存，而是在操作期间使用临时目录

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

通常，在当前目录、父目录或用户配置目录中发现配置文件。

也可以使用 UV_NO_CONFIG 环境变量设置。

禁用 uv 管理的 Python 版本的使用。

相反，uv 将在系统上搜索合适的 Python 版本。

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

禁用网络访问。

禁用后，uv 将仅使用本地缓存的数据和本地可用的文件。

也可以使用 UV_OFFLINE 环境变量设置。

--project project

在给定的项目目录中运行命令。

所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境 (.venv) 也会被发现。

其他命令行参数（例如相对路径）将相对于当前工作目录进行解析。

请参阅 --directory 以完全更改工作目录。

此设置在 uv pip 界面中使用时无效。

也可以使用 UV_PROJECT 环境变量设置。

--quiet, -q

使用安静输出。

重复此选项，例如 -qq，将启用静默模式，其中 uv 不会将任何输出写入 stdout。

--token token

用于身份验证的 GitHub 令牌。不需要令牌，但可用于降低遇到速率限制的可能性

也可以使用 UV_GITHUB_TOKEN 环境变量进行设置。

--verbose, -v

使用详细输出。

您可以使用 RUST_LOG 环境变量配置细粒度日志记录。 (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

uv self version

显示 uv 的版本

用法

uv self version [OPTIONS]

Options (选项)

--allow-insecure-host, --trusted-host allow-insecure-host

允许与主机建立不安全连接。

可以多次提供。

期望接收主机名（例如，localhost）、主机端口对（例如，localhost:8080）或 URL（例如，https://）。

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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 环境变量设置。

--color color-choice

控制输出中颜色的使用。

默认情况下，uv 在写入终端时会自动检测对颜色的支持。

可能的值

auto：仅当输出进入支持的终端或 TTY 时才启用彩色输出
always：无论检测到的环境如何，都启用彩色输出
never：禁用彩色输出

--config-file config-file

用于配置的 uv.toml 文件的路径。

虽然 uv 配置可以包含在 pyproject.toml 文件中，但在此上下文中不允许。

也可以使用 UV_CONFIG_FILE 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

相对路径以给定目录为基础进行解析。

请参阅 --project 以仅更改项目根目录。

--help, -h

显示此命令的简明帮助

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

--no-cache, --no-cache-dir, -n

避免从缓存读取或写入缓存，而是在操作期间使用临时目录

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

通常，在当前目录、父目录或用户配置目录中发现配置文件。

也可以使用 UV_NO_CONFIG 环境变量设置。

禁用 uv 管理的 Python 版本的使用。

相反，uv 将在系统上搜索合适的 Python 版本。

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。

禁用网络访问。

禁用后，uv 将仅使用本地缓存的数据和本地可用的文件。

也可以使用 UV_OFFLINE 环境变量设置。

--output-format output-format

--project project

在给定的项目目录中运行命令。

所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境 (.venv) 也会被发现。

其他命令行参数（例如相对路径）将相对于当前工作目录进行解析。

请参阅 --directory 以完全更改工作目录。

此设置在 uv pip 界面中使用时无效。

也可以使用 UV_PROJECT 环境变量设置。

--quiet, -q

使用安静输出。

重复此选项，例如 -qq，将启用静默模式，其中 uv 不会将任何输出写入 stdout。

--short

仅打印版本

--verbose, -v

使用详细输出。

您可以使用 RUST_LOG 环境变量配置细粒度日志记录。 (https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)

uv generate-shell-completion

生成 shell 补全

用法

uv generate-shell-completion [OPTIONS] <SHELL>

参数

SHELL: 为其生成补全脚本的 shell

Options (选项)

--allow-insecure-host, --trusted-host allow-insecure-host

允许与主机建立不安全连接。

可以多次提供。

期望接收主机名（例如，localhost）、主机端口对（例如，localhost:8080）或 URL（例如，https://）。

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您受到 MITM 攻击。

也可以使用 UV_INSECURE_HOST 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

相对路径以给定目录为基础进行解析。

请参阅 --project 以仅更改项目根目录。

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

禁用 uv 管理的 Python 版本的使用。

相反，uv 将在系统上搜索合适的 Python 版本。

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

--project project

在给定的项目目录中运行命令。

所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历目录树来发现，项目的虚拟环境 (.venv) 也会被发现。

其他命令行参数（例如相对路径）将相对于当前工作目录进行解析。

请参阅 --directory 以完全更改工作目录。

此设置在 uv pip 界面中使用时无效。

也可以使用 UV_PROJECT 环境变量设置。

uv help

显示命令的文档

用法

uv help [OPTIONS] [COMMAND]...

参数

COMMAND

Options (选项)

--allow-insecure-host, --trusted-host allow-insecure-host

允许与主机建立不安全连接。

可以多次提供。

期望接收主机名（例如，localhost）、主机端口对（例如，localhost:8080）或 URL（例如，https://）。

警告：此列表中包含的主机将不会针对系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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 环境变量设置。

--color color-choice

控制输出中颜色的使用。

默认情况下，uv 在写入终端时会自动检测对颜色的支持。

可能的值

auto：仅当输出进入支持的终端或 TTY 时才启用彩色输出
always：无论检测到的环境如何，都启用彩色输出
never：禁用彩色输出

--config-file config-file

用于配置的 uv.toml 文件的路径。

虽然 uv 配置可以包含在 pyproject.toml 文件中，但在此上下文中不允许。

也可以使用 UV_CONFIG_FILE 环境变量设置。

--directory directory

在运行命令之前更改为给定的目录。

相对路径以给定目录为基础进行解析。

请参阅 --project 以仅更改项目根目录。

--help, -h

显示此命令的简明帮助

要求使用 uv 管理的 Python 版本。

默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv 管理的 Python 版本，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。

也可以使用 UV_MANAGED_PYTHON 环境变量设置。

是否从平台的本机证书存储加载 TLS 证书。

默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。 webpki-roots 是来自 Mozilla 的一组可靠的信任根，在 uv 中包含它们可以提高可移植性和性能（尤其是在 macOS 上）。

但是，在某些情况下，您可能需要使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，用于强制代理）。

也可以使用 UV_NATIVE_TLS 环境变量设置。

--no-cache, --no-cache-dir, -n

避免从缓存读取或写入缓存，而是在操作期间使用临时目录

也可以使用 UV_NO_CACHE 环境变量设置。

避免发现配置文件 (pyproject.toml, uv.toml)。

通常，在当前目录、父目录或用户配置目录中发现配置文件。

也可以使用 UV_NO_CONFIG 环境变量设置。

禁用 uv 管理的 Python 版本的使用。

相反，uv 将在系统上搜索合适的 Python 版本。

也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。

--no-pager

打印帮助时禁用分页器

隐藏所有进度输出。

例如，微调器或进度条。

也可以使用 UV_NO_PROGRESS 环境变量设置。

禁用 Python 的自动下载。