uv - reference [官方文档翻译]

---

参考

https://docs.astral.sh/uv/reference/

参考文献部分提供了关于 uv 特定部分的信息：

• 命令: uv 的命令行接口参考。
• 设置: uv配置方案的参考。
• Resolver: uv 的 resolver 内部细节
• 政策: uv 的版本策略、平台支持策略和许可证。
  寻找更广泛的概述？查看概念文档。

---

CLI 参考文档

---

uv

一个非常快速的 Python 包管理器。

---

使用方法

uv [OPTIONS] <COMMAND>

---

命令

• uv run
  运行命令或脚本
• uv init
  创建新项目
• uv add
  向项目添加依赖项
• uv remove
  从项目中移除依赖项
• uv sync
  更新项目的环境
• uv lock
  更新项目的锁文件
• uv export
  将项目的锁文件导出为其他格式
• uv tree
  显示项目的依赖树
• uv tool
  运行并安装由 Python 包提供的命令
• uv python
  管理Python版本和安装
• uv pip
  使用与 pip 兼容的界面管理 Python 包
• uv venv
  创建虚拟环境
• uv build
  将 Python 包构建为源分布和 wheels
• uv publish
  将分布上传到索引
• uv cache
  管理uv的缓存
• uv self
  管理uv可执行文件
• uv version
  显示uv的版本
• uv help
  显示命令的文档

---

uv 运行

运行一个命令或脚本。

确保命令在 Python 环境中运行。

当与以 .py 或 HTTP(S) URL 结尾的文件一起使用时，该文件将被视为脚本，并使用 Python 解释器运行，即 uv run file.py 等同于 uv run python file.py。对于 URL，脚本在执行前会临时下载。如果脚本包含内联依赖元数据，它将被安装到一个隔离的临时环境中。当与 - 一起使用时，输入将从 stdin 读取，并被视为 Python 脚本。

当在项目中使用时，将在调用命令之前创建和更新项目环境。

当在项目外部使用时，如果在当前目录或父目录中找到了虚拟环境，则命令将在该环境中运行。否则，命令将在发现的解释器环境中运行。

命令（或脚本）后面的参数不会被解释为 uv 的参数。所有 uv 选项都必须在命令之前提供，例如 uv run --verbose foo。可以使用 -- 来分离命令和 uv 选项，以便清晰，例如 uv run --python 3.12 -- python。

---

使用方法

uv run [OPTIONS] [COMMAND]

---

选项

• --active
  优先使用活动虚拟环境而不是项目的虚拟环境。如果项目虚拟环境处于活动状态或没有活动虚拟环境，则此选项没有效果。
• --all-extras
  包含所有可选依赖。可选依赖通过 pyproject.toml 中的 project.optional-dependencies 定义。此选项仅在项目运行时可用。
• --all-groups
  包含所有依赖组中的依赖项。“–no-group” 可用于排除特定组。
• --all-packages
  使用已安装的所有工作区成员运行命令。工作区的环境 (.venv) 将更新以包含所有工作区成员。通过 --extra、--group 或相关选项指定的任何额外或组都将应用于所有工作区成员。
• --allow-insecure-host allow-insecure-host
  允许到主机的非安全连接。可以多次提供。期望接收主机名（例如，localhost）、主机-端口号对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：此列表中包含的主机将不会与系统证书存储进行验证。仅在安全网络和已验证源中使用 --allow-insecure-host，因为它绕过 SSL 验证，可能会使您容易受到中间人攻击。也可以通过 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
  在安装后编译 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, -C config-setting
  以 KEY=VALUE 对的形式传递给 PEP 517 构建后端的设置。
• --default-index default-index
  默认包索引的 URL（默认：https://pypi.org/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
  包含来自指定额外名称的可选依赖项。可以多次提供。可选依赖通过 pyproject.toml 中的 project.optional-dependencies 定义。此选项仅在项目运行时可用。
• --extra-index-url extra-index-url
  （已弃用：请使用 --index 代替）除 --index-url 之外要使用的额外包索引的 URL。接受符合 PEP 503 的存储库（简单的存储库 API），或以相同格式布局的本地目录。通过此标志提供的所有索引的优先级高于通过 --extra-index-url 标志指定的索引。当多次提供 --extra-index-url 标志时，早期值具有优先权。也可以通过 UV_EXTRA_INDEX_URL 环境变量设置。
• --find-links, -f find-links
  除了在注册表索引中找到的索引外，还要搜索候选分发的位置。如果是一个路径，目标必须是一个包含包（.whl）或源分发（例如，.tar.gz 或 .zip）的目录。如果是一个 URL，页面必须包含一个符合上述格式的包文件的平铺列表。也可以通过 UV_FIND_LINKS 环境变量设置。
• --fork-strategy fork-strategy
  在多个 Python 版本和平台之间选择给定包的多个版本时要使用的策略。默认情况下，uv 将优化为为每个支持的 Python 版本（requires-python）选择每个包的最新版本，同时最小化跨平台的选定版本数。在 fewest 下，uv 将为每个包最小化选定的版本数，优先考虑与更广泛的受支持 Python 版本或平台兼容的较旧版本。也可以通过 UV_FORK_STRATEGY 环境变量设置。可能的值：“fewest”：优化为为每个包选择最少的版本数。如果它们与更广泛的受支持 Python 版本或平台兼容，则可能会优先考虑较旧的版本；“requires-python”：优化为为每个包选择每个受支持 Python 版本支持的最新版本。
• --frozen
  不更新 uv.lock 文件运行。而不是检查锁文件是否最新，使用锁文件中的版本作为真实来源。如果锁文件缺失，uv 将以错误退出。如果 pyproject.toml 包含尚未包含在锁文件中的依赖项更改，则它们将不会存在于环境中。也可以通过 UV_FROZEN 环境变量设置。
• --group group
  包含来自指定依赖组的依赖项。可以多次提供。
• --gui-script
  将给定路径作为 Python GUI 脚本运行。使用 --gui-script 将尝试将路径解析为 PEP 723 脚本，并使用 pythonw.exe 运行，而不管其扩展名如何。仅在 Windows 上可用。
• [--help](https://docs.astral.sh/uv/reference/cli/#

---

uv init

创建一个新的项目。

遵循 pyproject.toml 规范。

如果目标位置已存在 pyproject.toml，uv 将以错误退出。

如果在目标路径的任何父目录中找到 pyproject.toml，项目将被添加为父项目的成员。

某些项目状态只有在需要时才会创建，例如，项目虚拟环境 (.venv) 和锁文件 (uv.lock) 在第一次同步时才会懒加载创建。

---

使用方法

uv init [OPTIONS] [PATH]

---

参数

• PATH
  使用项目/脚本的路径。当初始化应用程序或库时默认为当前工作目录；初始化脚本时必须提供。接受相对路径和绝对路径。如果在目标路径的任何父目录中找到 pyproject.toml 文件，则该项目将被添加为父项目的 workspace 成员，除非提供了 --no-workspace。

---

选项

• --allow-insecure-host allow-insecure-host
  允许到主机的非安全连接。可以多次提供。预期接收主机名（例如，localhost）、主机端口对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：列表中包含的主机将不会与系统证书存储进行验证。仅在安全网络和验证源中使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您容易受到中间人攻击。也可以使用 UV_INSECURE_HOST 环境变量设置。
• --app
  为应用程序创建项目。如果未请求 --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 作为项目构建后端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
  为库创建项目。库是旨在构建和作为 Python 软件包分发的项目。
• --managed-python
  需要使用 uv-managed Python 版本。默认情况下，uv 倾向于使用它管理的 Python 版本。但是，如果没有安装 uv-managed Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。也可以使用 UV_MANAGED_PYTHON 环境变量设置。
• --name name
  项目的名称。默认为目录的名称。
• --native-tls
  是否从平台的本机证书存储加载 TLS 证书。默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。webpki-roots 是来自 Mozilla 的可靠信任根集合，将其包含在 uv 中可以改善可移植性和性能（特别是在 macOS 上）。但是，在某些情况下，您可能想使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的企业信任根（例如，强制代理），可以使用 UV_NATIVE_TLS 环境变量设置。
• --no-cache, -n
  避免从缓存读取或写入，而是在整个操作期间使用临时目录。也可以使用 UV_NO_CACHE 环境变量设置。
• --no-config
  避免发现配置文件（pyproject.toml、uv.toml）。通常，配置文件会在当前目录、父目录或用户配置目录中发现。也可以使用 UV_NO_CONFIG 环境变量设置。
• --no-description
  禁用项目的描述
• --no-managed-python
  禁用 uv-managed Python 版本的使用。相反，uv 将在系统上搜索合适的 Python 版本。也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。
• --no-package
  不要设置项目以便构建为 Python 软件包。不包括项目中的 [build-system]。在使用 --app 时这是默认行为。
• --no-pin-python
  不要为项目创建 .python-version 文件。默认情况下，uv 将创建一个包含发现的 Python 解释器次要版本的 .python-version 文件，这将导致后续 uv 命令使用该版本。
• --no-progress
  隐藏所有进度输出。例如，旋转器或进度条。也可以使用 UV_NO_PROGRESS 环境变量设置。
• --no-python-downloads
  禁用 Python 的自动下载。
• --no-readme
  不要创建 README.md 文件
• --no-workspace
  避免发现工作区并创建独立项目。默认情况下，uv 在当前目录或任何父目录中搜索工作区。
• --offline
  禁用网络访问。禁用时，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 接口中使用时没有效果。
• --python, -p python
  要使用的 Python 解释器以确定最小支持的 Python 版本。见 uv python 以查看支持的请求格式。也可以使用 UV_PYTHON 环境变量设置。
• --quiet, -q
  不打印任何输出
• --script
  创建脚本。脚本是一个独立的文件，其中嵌入了对其依赖关系的元数据枚举，以及任何 Python 版本要求，如 PEP 723 规范中定义。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）
• --version, -V
  显示 uv 版本

---

uv add

将依赖项添加到项目中。

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

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

如果没有为依赖项提供约束或URL，则添加一个等于最新兼容版本的下限，例如，>=1.2.3，除非提供了 --frozen，在这种情况下不会执行解析。

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

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

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

---

使用方法

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

---

参数

• PACKAGES
  要添加的软件包，作为 PEP 508 需求（例如，ruff==0.5.0）

---

选项

• --active
  优先使用活动虚拟环境而不是项目的虚拟环境。如果项目虚拟环境是活动的或没有活动虚拟环境，则此选项不起作用。
• --allow-insecure-host allow-insecure-host
  允许与主机的不安全连接。可以多次提供。期望接收主机名（例如，localhost）、主机-端口号对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：列入此列表的主机将不会与系统的证书存储进行验证。仅在安全网络和已验证源中使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您面临中间人攻击。也可以通过 UV_INSECURE_HOST 环境变量设置。
• --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 将在写入终端或 TTY 时自动检测对颜色的支持。可能的值：auto：仅在输出将发送到支持颜色的终端或 TTY 时启用彩色输出always：无论检测到的环境如何，都启用彩色输出never：禁用彩色输出
• --compile-bytecode
  在安装后编译 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, -C config-setting
  以 KEY=VALUE 对的形式传递给 PEP 517 构建后端的设置
• --constraints, -c constraints
  使用给定的要求文件约束版本。约束文件类似于 requirements.txt 的文件，它仅控制要安装的依赖项的 版本。约束将 不会 添加到项目的 pyproject.toml 文件中，但在依赖项解析期间将被尊重。这与 pip 的 --constraint 选项等效。也可以通过 UV_CONSTRAINT 环境变量设置。
• --default-index default-index
  默认包索引的 URL（默认：https://pypi.org/simple）。接受符合 PEP 503 的存储库（简单存储库 API），或以相同格式布局的本地目录。此标志提供的索引比通过 --index 标志指定的所有其他索引具有较低优先级。也可以通过 UV_DEFAULT_INDEX 环境变量设置。
• --dev
  将要求添加到开发依赖项组。此选项是 --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），或以相同格式布局的本地目录。通过此标志提供的所有索引都比通过 --extra-index-url 标志指定的索引具有更高的优先级。当提供多个 --extra-index-url 标志时，较早的值具有更高的优先级。也可以通过 UV_EXTRA_INDEX_URL 环境变量设置。
• --find-links, -f find-links
  在除注册表索引之外的位置搜索候选分布的位置。如果路径，目标必须是包含包作为 wheel 文件（.whl）或源分发（例如，.tar.gz 或 .zip）的目录。如果 URL，页面必须包含一个包含上述格式描述的包文件的平坦列表。也可以通过 UV_FIND_LINKS 环境变量设置。
• --fork-strategy fork-strategy
  在选择给定包的多个版本时使用的策略，涉及 Python 版本和平台。默认情况下，uv 将优化选择每个支持的 Python 版本（requires-python）的每个包的最新版本，同时最小化跨平台的选定版本数量。在 fewest 下，uv 将为每个包最小化选定版本的数量，优先考虑与更广泛的受支持的 Python 版本或平台兼容的较旧版本。也可以通过 UV_FORK_STRATEGY 环境变量设置。可能的值：fewest：为每个包优化选择最少的版本数量。如果较旧版本与更广泛的受支持的 Python 版本或平台兼容，则可能会优先考虑较旧版本requires-python：为每个支持的 Python 版本优化选择每个包的最新支持版本
• --frozen
  添加依赖项而无需重新锁定项目。项目环境将不会同步。也可以通过 UV_FROZEN 环境变量设置。
• --group group
  将要求添加到指定的依赖项组。这些要求将不会包含在项目的发布元数据中。
• --help, -h
  显示此命令的简洁帮助信息
• --index index
  解析依赖项时使用的 URL，除默认索引之外。接受符合 PEP 503 的存储库（简单存储库 API），或以相同格式布局的本地目录。通过此标志提供的所有索引都比通过 --default-index 标志指定的索引具有更高的优先级。当提供多个 --index 标志时，较早的值具有更高的优先级。也可以通过 UV_INDEX 环境变量设置。
• --index-strategy index-strategy
  解析多个索引 URL 时使用的策略。默认情况下，uv 将在给定包可用的第一个索引处停止，并将解析限制在第一个索引上存在的那些上（first-index）。这可以防止“依赖项混淆”攻击，其中攻击者可以将恶意包上传到替代索引下，以相同的名称。也可以通过 UV_INDEX_STRATEGY 环境变量设置。可能的值：first-index：仅使用为给定包名称返回匹配的第一个索引的结果unsafe-first-match：在所有索引中搜索每个包名称，在移动到下一个索引之前耗尽第一个索引的版本unsafe-best-match：在所有索引中搜索每个包名称，优先考虑找到的“最佳”版本。如果包版本在多个索引中，则仅查看第一个索引的条目
• --index-url, -i index-url
  （已弃用：使用 --default-index 代替）Python 包索引的 URL（默认：https://pypi.org/simple）。接受符合 PEP 503 的存储库（简单存储库 API），或以相同格式布局的本地目录。此标志提供的索引比通过 --extra-index-url 标志指定的索引具有较低的优先级。也可以通过 UV_INDEX_URL 环境变量设置。
• --keyring-provider keyring-provider
  尝试使用 keyring 对索引 URL 进行身份验证。目前，仅支持 --keyring-provider subprocess，它配置 uv 使用 keyring CLI 来处理身份验证。默认为 disabled。也可以通过 UV_KEYRING_PROVIDER 环境变量设置。可能的值：disabled：不要使用 keyring 进行凭据查找subprocess：使用 keyring 命令进行凭据查找
• --link-mode link-mode
  安装全局缓存中的包时使用的方法。默认为 macOS 上的 clone（也称为 Copy-on-Write），Linux 和 Windows 上的 hardlink。也可以通过 UV_LINK_MODE 环境变量设置。可能的值：clone：从 wheel 复制（即复制-on-write）包到 site-packages 目录copy：将包从 wheel 复制到 site-packages 目录hardlink：从 wheel 创建硬链接到 site-packages 目录symlink：从 wheel 创建符号链接到 site-packages 目录
• --locked
  断言 uv.lock 将保持不变。需要锁文件是最新的。如果锁文件丢失或需要更新，uv 将以错误退出。也可以通过 UV_LOCKED 环境变量设置。
• --managed-python
  要求使用 uv-managed Python 版本。默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv-managed Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。也可以通过 UV_MANAGED_PYTHON 环境变量设置。
• --marker, -m marker
  将此标记应用于所有添加的包
• --native-tls
  是否从平台的本机证书存储加载 TLS 证书。默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。webpki-roots 是来自 Mozilla 的可靠的一组信任根，将它们包含在 uv 中可以提高可移植性和性能（尤其是在 macOS 上）。但是，在某些情况下，您可能想使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的企业信任根（例如，强制代理），则更是如此。也可以通过 UV_NATIVE_TLS 环境变量设置。
• [--no-binary](https://docs.astral.sh/uv

---

uv remove

从项目中移除依赖。

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

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

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

如果请求的任何依赖项不存在于项目中，uv 将以错误退出。

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

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

---

使用方法

uv remove [OPTIONS] <PACKAGES>...

---

参数

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

---

选项

• --active
  优先使用活动的虚拟环境，而不是项目的虚拟环境。如果项目虚拟环境是活动的或者没有活动的虚拟环境，则此选项没有任何效果。
• --allow-insecure-host allow-insecure-host
  允许与主机的不安全连接。可以多次提供。期望接收主机名（例如，localhost）、主机-端口号对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：包含在此列表中的主机将不会与系统证书存储进行验证。仅在安全网络和验证源中使用 --allow-insecure-host，因为它绕过 SSL 验证，可能会使您面临中间人攻击。也可以通过 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 会自动检测在向终端或支持颜色的 TTY 写入时是否启用颜色输出。可能的值：auto：仅在输出将发送到终端或支持颜色的 TTY 时启用颜色输出；always：无论检测到的环境如何都启用颜色输出；never：禁用颜色输出
• --compile-bytecode
  安装后编译 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, -C config-setting
  要传递给 PEP 517 构建后端的设置，指定为 KEY=VALUE 对
• --default-index default-index
  默认包索引的 URL（默认：https://pypi.org/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）的存储库，或以相同格式布局的本地目录。通过此标志提供的所有索引的优先级高于通过 --extra-index-url 标志指定的索引（默认为 PyPI）。当提供多个 --extra-index-url 标志时，较早的值具有优先权。也可以通过 UV_EXTRA_INDEX_URL 环境变量设置。
• --find-links, -f find-links
  在除注册表索引中找到的之外搜索候选分发的位置。如果是一个路径，目标必须是包含包作为 wheel 文件（.whl）或源分发（例如，.tar.gz 或 .zip）的目录。如果是一个 URL，页面必须包含一个符合上述格式的包文件链接的平面列表。也可以通过 UV_FIND_LINKS 环境变量设置。
• --fork-strategy fork-strategy
  在选择给定包的多个版本（跨 Python 版本和平台）时使用的策略。
  默认情况下，uv 会优化选择每个支持的 Python 版本（requires-python）的每个包的最新版本，同时最小化跨平台选择的版本数量。
  在 fewest 下，uv 将最小化每个包选择的版本数量，优先选择与更广泛的支持的 Python 版本或平台兼容的较旧版本。也可以通过 UV_FORK_STRATEGY 环境变量设置。
  可能的值：fewest：为每个包优化选择最少的版本数。
  如果它们与更广泛的支持的 Python 版本或平台兼容，则可能优先选择较旧的版本；requires-python：为每个支持的 Python 版本优化选择每个包的最新支持的版本
• --frozen
  删除依赖项而无需重新锁定项目。项目环境将不会同步。也可以通过 UV_FROZEN 环境变量设置。
• --group group
  从指定的依赖组中删除包
• --help, -h
  显示此命令的简洁帮助信息
• --index index
  在解析依赖项时要使用的 URL，除了默认索引之外。接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。
  通过此标志提供的所有索引的优先级高于通过 --default-index 标志指定的索引（默认为 PyPI）。
  当提供多个 --index 标志时，较早的值具有优先权。也可以通过 UV_INDEX 环境变量设置。
• --index-strategy index-strategy
  在针对多个索引 URL 解析时使用的策略。默认情况下，uv 会停止在第一个包含给定包的索引上，并将解析限制在该第一个索引上（first-index）。这可以防止“依赖混淆”攻击，即攻击者可以在替代索引中上传与同一名称相同的恶意包。
  也可以通过 UV_INDEX_STRATEGY 环境变量设置。可能的值：first-index：仅使用第一个索引返回给定包名称匹配的结果；unsafe-first-match：搜索所有索引中的每个包名称，在移动到下一个索引之前耗尽第一个索引的版本；unsafe-best-match：搜索所有索引中的每个包名称，优先选择找到的“最佳”版本。如果包版本在多个索引中，则仅查看第一个索引的条目
• --index-url, -i index-url
  （已弃用：使用 --default-index 代替）Python 包索引的 URL（默认：https://pypi.org/simple）。接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。
  此标志给出的索引的优先级低于通过 --extra-index-url 标志指定的索引。也可以通过 UV_INDEX_URL 环境变量设置。
• --keyring-provider keyring-provider
  尝试使用 keyring 进行索引 URL 的身份验证。目前，仅支持 --keyring-provider subprocess，它配置 uv 使用 keyring CLI 处理身份验证。默认为 disabled。也可以通过 UV_KEYRING_PROVIDER 环境变量设置。可能的值：disabled：不要使用 keyring 进行凭据查找；subprocess：使用 keyring 命令进行凭据查找
• --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 目录的符号链接
• --locked
  断言 uv.lock 将保持不变。要求锁文件是最新的。如果锁文件丢失或需要更新，uv 将以错误退出。也可以通过 UV_LOCKED 环境变量设置。
• --managed-python
  要求使用 uv-managed Python 版本。默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv-managed Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。也可以通过 UV_MANAGED_PYTHON 环境变量设置。
• --native-tls
  是否从平台的本地证书存储加载 TLS 证书。默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。webpki-roots 是来自 Mozilla 的可靠的一组信任根，将它们包含在 uv 中可以提高可移植性和性能（尤其是在 macOS 上）。
  但是，在某些情况下，您可能想使用平台的本地证书存储，特别是如果您依赖于包含在系统证书存储中的企业信任根（例如，强制代理），则尤其如此。也可以通过 UV_NATIVE_TLS 环境变量设置。
• --no-binary
  不安装预构建的 wheel。给定的包将从头开始构建和安装。解析器仍会使用可用的预构建 wheel 提取包元数据，如果有的话。也可以通过 UV_NO_BINARY 环境变量设置。
• --no-binary-package no-binary-package
  不为特定包安装预构建的 wheel。也可以通过 UV_NO_BINARY_PACKAGE 环境变量设置。
• --no-build
  不构建源分发。当启用时，解析将不会运行任意 Python 代码。
  将重用已构建源分发的缓存的 wheel，但需要构建分发的操作将出错退出。也可以通过 UV_NO_BUILD 环境变量设置。
• --no-build-isolation
  禁用构建源分发时的隔离。假设 PEP 518 中指定的构建依赖项已经安装。也可以通过 UV_NO_BUILD_ISOLATION 环境变量设置。
• --no-build-isolation-package no-build-isolation-package
  构建源分发时禁用特定包的隔离。假设包的 PEP 518 中指定的构建依赖项已经安装。
• --no-build-package no-build-package
  不为特定包构建源分发。也可以通过 UV_NO_BUILD_PACKAGE 环境变量设置。
• --no-cache, -n
  避免从缓存中读取或写入，而是在整个操作期间使用临时目录。也可以通过 UV_NO_CACHE 环境变量设置。
• --no-config
  避免发现配置文件（pyproject.toml、uv.toml）。通常，配置文件会在当前目录、父目录或用户配置目录中发现。也可以通过 UV_NO_CONFIG 环境变量设置。
• --no-index
  忽略注册表索引（例如，PyPI），而是依赖直接 URL 依赖项和通过 --find-links 提供的依赖项
• --no-managed-python
  禁用 uv-managed Python 版本的使用。相反，uv 将在系统上搜索合适的 Python 版本。也可以通过 UV_NO_MANAGED_PYTHON 环境变量设置。
• --no-progress
  隐藏所有进度输出。例如，旋转器或进度条。也可以通过 UV_NO_PROGRESS 环境变量设置。
• --no-python-downloads
  禁用 Python 的自动下载。
• --no-sources
  忽略 tool.uv.sources 表在解析依赖项时。用于锁定符合标准、可发布的包元数据，而不是使用任何工作区

---

uv 同步

更新项目的环境。

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

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

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

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

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

请注意，从锁文件安装时，uv 不会为已撤回的包版本提供警告。

---

使用方法

uv sync [OPTIONS]

---

选项

• --active
  同步依赖到活动虚拟环境。在设置 VIRTUAL_ENV 环境变量的情况下，将优先选择活动虚拟环境，而不是为项目或脚本创建或更新虚拟环境。
• --all-extras
  包含所有可选依赖项。当两个或多个 extras 在 tool.uv.conflicts 中声明为冲突时，使用此标志将始终导致错误。请注意，所有可选依赖项始终包含在解析中；此选项仅影响要安装的包的选择。
• --all-groups
  包含所有依赖组的依赖项。“–no-group” 可用于排除特定组。
• --all-packages
  同步工作区中的所有包。工作区的环境 (.venv) 将更新以包含所有工作区成员。通过 --extra、--group 或相关选项指定的任何 extras 或组都将应用于所有工作区成员。
• --allow-insecure-host allow-insecure-host
  允许与主机建立不安全连接。可以多次提供。期望接收主机名（例如，localhost）、主机-端口对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：列入此列表的主机将不会与系统的证书存储进行验证。仅在安全网络中带有验证源的情况下使用 --allow-insecure-host，因为它绕过 SSL 验证，可能会使您容易受到中间人攻击。还可以通过 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
  在安装后编译 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, -C config-setting
  作为 KEY=VALUE 对传递给 PEP 517 构建后端的设置
• --default-index default-index
  默认包索引的 URL（默认：https://pypi.org/simple）。接受符合 PEP 503（简单存储库 API）的存储库，或按相同格式排列的本地目录。此标志给出的索引的优先级低于通过 --index 标志指定的所有其他索引。可以通过 UV_DEFAULT_INDEX 环境变量设置。
• --directory directory
  在运行命令之前更改到指定的目录。相对路径将以给定目录为基准解析。有关仅更改项目根目录的信息，请参阅 --project。
• --dry-run
  执行干运行，不写入锁文件或修改项目环境。在干运行模式下，uv 将解析项目的依赖项，并报告对锁文件和项目环境的最终更改，但不会对其进行修改。
• --exclude-newer exclude-newer
  限制候选包为在给定日期之前上传的包。接受 RFC 3339 时间戳（例如，2006-12-02T02:07:43Z）和系统配置时区中相同格式的本地日期（例如，2006-12-02）。可以通过 UV_EXCLUDE_NEWER 环境变量设置。
• --extra extra
  从指定的 extra 名称包含可选依赖项。可以多次提供。当指定了多个 extras 或组，并且它们出现在 tool.uv.conflicts 中时，uv 将报告错误。请注意，所有可选依赖项始终包含在解析中；此选项仅影响要安装的包的选择。
• --extra-index-url extra-index-url
  （已弃用：使用 --index 代替）除了 --index-url 之外使用的额外包索引 URL。接受符合 PEP 503（简单存储库 API）的存储库，或按相同格式排列的本地目录。通过此标志提供的所有索引的优先级高于由 --extra-index-url 标志指定的索引（默认为 PyPI）。当提供多个 --extra-index-url 标志时，早期值具有优先权。可以通过 UV_EXTRA_INDEX_URL 环境变量设置。
• --find-links, -f find-links
  在注册表中找到候选分布的位置，除了在索引中找到的之外。如果是一个路径，目标必须是一个包含包（.whl）或源分发（例如，.tar.gz 或 .zip）的目录。如果是一个 URL，页面必须包含一个符合上述格式的包文件链接列表。可以通过 UV_FIND_LINKS 环境变量设置。
• --fork-strategy fork-strategy
  选择给定包在不同 Python 版本和平台上的多个版本时要使用的策略。默认情况下，uv 将优化选择每个支持的 Python 版本（requires-python）的每个包的最新版本，同时最大限度地减少跨平台选择版本的数量。
  在 fewest 下，uv 将最大限度地减少每个包选择版本的数目，优先选择与更广泛的支持的 Python 版本或平台兼容的较旧版本。可以通过 UV_FORK_STRATEGY 环境变量设置。可能的值：fewest：为每个包优化选择最少数量的版本。如果它们与更广泛的支持的 Python 版本或平台兼容，则可能优先选择较旧的版本requires-python：为每个支持的 Python 版本优化选择每个包的最新支持的版本
• --frozen
  同步而不更新 uv.lock 文件。而不是检查锁文件是否最新，使用锁文件中的版本作为事实来源。如果锁文件丢失，uv 将退出并显示错误。如果 pyproject.toml 包含尚未包含在锁文件中的依赖项更改，则它们将不会存在于环境中。可以通过 UV_FROZEN 环境变量设置。
• --group group
  从指定的依赖项组包含依赖项。当指定了多个 extras 或组，并且它们出现在 tool.uv.conflicts 中时，uv 将报告错误。可以多次提供。
• --help, -h
  显示此命令的简明帮助信息
• --index index
  在解析依赖项时要使用的 URL，除默认索引之外。接受符合 PEP 503（简单存储库 API）的存储库，或按相同格式排列的本地目录。通过此标志提供的所有索引的优先级高于由 --default-index 标志指定的索引（默认为 PyPI）。当提供多个 --index 标志时，早期值具有优先权。可以通过 UV_INDEX 环境变量设置。
• --index-strategy index-strategy
  在针对多个索引 URL 解析时要使用的策略。默认情况下，uv 将在第一个包含给定包的索引上停止，并将解析限制在第一个索引上存在的那些上（first-index）。这可以防止“依赖项混淆”攻击，攻击者可以在备用索引上上传与同一名称相同的恶意包。可以通过 UV_INDEX_STRATEGY 环境变量设置。可能的值：first-index：仅使用第一个索引返回给定包名称的匹配结果unsafe-first-match：在所有索引中搜索每个包名称，在移动到下一个索引之前耗尽第一个索引的版本unsafe-best-match：在所有索引中搜索每个包名称，优先选择找到的“最佳”版本。如果包版本在多个索引中，则仅查看

---

uv 锁定

更新项目的锁定文件。

如果项目的锁定文件 (uv.lock) 不存在，它将被创建。如果存在锁定文件，其内容将被用作解析的首选项。

如果没有更改项目的依赖项，除非提供了 --upgrade 标志，否则锁定将没有任何效果。

---

使用方法

uv lock [OPTIONS]

---

选项

• --allow-insecure-host allow-insecure-host
  允许对主机的不安全连接。可以多次提供。期望接收主机名（例如，localhost）、主机-端口对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：列出的主机将不会与系统的证书存储进行验证。仅在安全网络和验证源中使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您面临中间人攻击。也可以通过 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
  检查锁文件是否最新。断言在解决后 uv.lock 将保持不变。如果锁文件丢失或需要更新，uv 将以错误退出。等同于 --locked。也可以通过 UV_LOCKED 环境变量设置。
• --check-exists
  断言存在 uv.lock，而无需检查它是否是最新的。等同于 --frozen。也可以通过 UV_FROZEN 环境变量设置。
• --color color-choice
  控制输出中的颜色使用。默认情况下，uv 将在写入终端或 TTY 时自动检测对颜色的支持。可能的值：auto：仅在输出将发送到支持颜色的终端或 TTY 时启用彩色输出always：无论检测到的环境如何，都启用彩色输出never：禁用彩色输出
• --config-file config-file
  用于配置的 uv.toml 文件的路径。虽然 uv 配置可以包含在 pyproject.toml 文件中，但在此上下文中不允许。也可以通过 UV_CONFIG_FILE 环境变量设置。
• --config-setting, -C config-setting
  要传递给 PEP 517 构建后端的设置，指定为 KEY=VALUE 对
• --default-index default-index
  默认包索引的 URL（默认为 https://pypi.org/simple）。接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式排列的本地目录。此标志给出的索引优先级低于通过 --index 标志指定的所有其他索引。也可以通过 UV_DEFAULT_INDEX 环境变量设置。
• --directory directory
  在运行命令之前更改到指定的目录。相对路径将以给定目录为基础解析。有关只更改项目根目录的信息，请参阅 --project。也可以通过 UV_DIRECTORY 环境变量设置。
• --dry-run
  执行 dry run，而不写入锁文件。在 dry run 模式下，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
  在注册表索引中找到的候选发行版所在的搜索位置，包括 --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 标志时，较早的值优先。也可以通过 UV_INDEX 环境变量设置。
• --index-strategy index-strategy
  解析多个索引 URL 时要使用的策略。默认情况下，uv 将在第一个包含给定包的索引处停止，并将解析限制在第一个索引上存在的那些上（first-index）。这可以防止“依赖混淆”攻击，攻击者可以将恶意软件包上传到替代索引的同一名称下。也可以通过 UV_INDEX_STRATEGY 环境变量设置。可能的值：first-index：仅使用第一个索引返回给定包名称匹配的结果unsafe-first-match：在所有索引中搜索每个包名称，在移动到下一个索引之前耗尽第一个索引的版本unsafe-best-match：在所有索引中搜索每个包名称，优先选择找到的“最佳”版本。如果包版本在多个索引中，则仅查看第一个索引的条目
• --index-url, -i index-url
  （已弃用：使用 --default-index 代替）Python 包索引的 URL（默认为 https://pypi.org/simple）。接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式排列的本地目录。由此标志给出的索引优先级低于通过 --extra-index-url 标志指定的所有其他索引。也可以通过 UV_INDEX_URL 环境变量设置。
• --keyring-provider keyring-provider
  尝试使用 keyring 进行索引 URL 的身份验证。目前，仅支持 --keyring-provider subprocess，它配置 uv 使用 keyring CLI 来处理身份验证。默认为 disabled。也可以通过 UV_KEYRING_PROVIDER 环境变量设置。可能的值：disabled：不使用 keyring 进行凭据查找subprocess：使用 keyring 命令进行凭据查找
• --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 目录
• --managed-python
  要求使用 uv-managed Python 版本。默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv-managed Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。也可以通过 UV_MANAGED_PYTHON 环境变量设置。
• --native-tls
  是否从平台的本地证书存储加载 TLS 证书。默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。webpki-roots 是来自 Mozilla 的可靠信任根集合，包括它们在 uv 中可以提高可移植性和性能（尤其是在 macOS 上）。但是，在某些情况下，您可能想使用平台的本地证书存储，特别是如果您依赖于包含在系统证书存储中的企业信任根（例如，强制代理），则更是如此。也可以通过 UV_NATIVE_TLS 环境变量设置。
• --no-binary
  不安装预构建的 wheel。给定的包将从头开始构建和安装。解析器仍会使用可用的预构建 wheel 来提取包元数据，如果有的话。也可以通过 UV_NO_BINARY 环境变量设置。
• --no-binary-package no-binary-package
  不为特定包安装预构建的 wheel。也可以通过 UV_NO_BINARY_PACKAGE 环境变量设置。
• --no-build
  不构建源发行版。当启用时，解析将不会运行任意 Python 代码。将重用已构建源发行版的缓存的 wheel，但需要构建发行版的操作将错误退出。也可以通过 UV_NO_BUILD 环境变量设置。
• --no-build-isolation
  禁用构建源发行版时的隔离。假设 PEP 518 指定的构建依赖项已经安装。也可以通过 UV_NO_BUILD_ISOLATION 环境变量设置。
• --no-build-isolation-package no-build-isolation-package
  构建源发行版时禁用特定包的隔离。假设 PEP 518 指定的包的构建依赖项已经安装。
• --no-build-package no-build-package
  不为特定包构建源发行版。也可以通过 UV_NO_BUILD_PACKAGE 环境变量设置。
• --no-cache, -n
  避免从缓存中读取或写入，而是在整个操作期间使用临时目录。也可以通过 UV_NO_CACHE 环境变量设置。
• --no-config
  避免发现配置文件（pyproject.toml、uv.toml）。通常，配置文件会在当前目录、父目录或用户配置目录中找到。也可以通过 UV_NO_CONFIG 环境变量设置。
• --no-index
  忽略注册表索引（例如，PyPI），而是依赖于直接 URL 依赖项和通过 --find-links 提供的依赖项
• --no-managed-python
  禁用 uv-managed Python 版本的使用。相反，uv 将在系统上搜索合适的 Python 版本。也可以通过 UV_NO_MANAGED_PYTHON 环境变量设置。
• --no-progress
  隐藏所有进度输出。例如，旋转器或进度条。也可以通过 UV_NO_PROGRESS 环境变量设置。
• --no-python-downloads
  禁止自动下载 Python。
• --no-sources
  在解析依赖项时忽略 tool.uv.sources 表。用于锁定符合标准、可发布的包元数据，而不是使用任何工作区、Git、URL 或本地路径源
• --offline
  禁用网络访问。当禁用时，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 接口中使用时，此设置没有效果。
• --python, -p python
  解析时要使用的 Python 解释器。Python 解释器在构建源发行版时用于确定包元数据（在没有 wheel 时），并且也是 requires-python 未设置时的最小 Python 版本的回退值。有关 Python 发现和受支持的请求格式的详细信息，请参阅 uv python。也可以通过 UV_PYTHON 环境变量设置。
• --quiet, -q
  不打印任何输出
• [--refresh](https://docs.astral.sh/uv/reference/cli/#uv-lock

---

uv 导出

将项目的锁定文件导出到另一种格式。

目前，仅支持 requirements-txt。

如果提供了 --locked 或 --frozen 标志，则项目在导出之前不会被重新锁定。

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

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

---

使用方法

uv export [OPTIONS]

---

选项

• --all-extras
  包含所有可选依赖项
• --all-groups
  包含所有依赖组的依赖项。可以使用 --no-group 来排除特定组。
• --all-packages
  导出整个工作区。将包含所有工作区成员的依赖项在导出的需求文件中。通过 --extra、--group 或相关选项指定的任何额外或组将应用于所有工作区成员。
• --allow-insecure-host allow-insecure-host
  允许与主机的不安全连接。可以多次提供。期望接收主机名（例如，localhost）、主机-端口对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：列表中包含的主机将不会与系统的证书存储进行验证。仅在安全网络和验证来源的情况下使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您容易受到中间人攻击。也可以通过 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 将在写入终端或支持 TTY 时自动检测对颜色的支持。可能的值：auto：仅在输出将发送到终端或支持颜色的 TTY 时启用彩色输出always：无论检测到的环境如何都启用彩色输出never：禁用彩色输出
• --config-file config-file
  要用于配置的 uv.toml 文件的路径。虽然 uv 配置可以包含在 pyproject.toml 文件中，但在此上下文中不允许。也可以通过 UV_CONFIG_FILE 环境变量设置。
• --config-setting, -C config-setting
  要传递给 PEP 517 构建后端的设置，指定为 KEY=VALUE 对
• --default-index default-index
  默认包索引的 URL（默认：https://pypi.org/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-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。[默认：requirements-txt]可能的值：requirements-txt：以 requirements.txt 格式导出
• --frozen
  在导出之前不要更新 uv.lock。如果不存在 uv.lock，uv 将退出并显示错误。也可以通过 UV_FROZEN 环境变量设置。
• --group group
  包含指定依赖组的依赖项。可以多次提供。
• --help, -h
  显示此命令的简洁帮助
• --index index
  在解析依赖项时要使用的 URL，除了默认索引之外。接受符合 PEP 503 的存储库（简单存储库 API），或以相同格式布局的本地目录。通过此标志提供的所有索引的优先级高于 --default-index 标志指定的索引（默认为 PyPI）。当提供多个 --index 标志时，较早的值具有优先级。也可以通过 UV_INDEX 环境变量设置。
• --index-strategy index-strategy
  在多个索引 URL 上解析时要使用的策略。默认情况下，uv 将在给定包可用时停止在第一个索引上，并将解析限制在该第一个索引上（first-index）。这可以防止“依赖混淆”攻击，其中攻击者可以将恶意包上传到备用索引。也可以通过 UV_INDEX_STRATEGY 环境变量设置。可能的值：first-index：仅使用第一个索引返回给定包名称的匹配结果的结果unsafe-first-match：搜索所有包名称跨所有索引，在移动到下一个索引之前耗尽第一个索引的版本unsafe-best-match：搜索所有包名称跨所有索引，优先选择找到的“最佳”版本。如果包版本在多个索引中，则仅查看第一个索引的条目
• --index-url, -i index-url
  （已弃用：使用 --default-index 代替）Python 包索引的 URL（默认：https://pypi.org/simple）。接受符合 PEP 503 的存储库（简单存储库 API），或以相同格式布局的本地目录。此标志给出的索引的优先级低于通过 --extra-index-url 标志指定的所有其他索引。也可以通过 UV_INDEX_URL 环境变量设置。
• --keyring-provider keyring-provider
  尝试使用 keyring 对索引 URL 进行身份验证。目前，仅支持 --keyring-provider subprocess，它配置 uv 使用 keyring CLI 来处理身份验证。默认为 disabled。也可以通过 UV_KEYRING_PROVIDER 环境变量设置。可能的值：disabled：不要使用 keyring 进行凭据查找subprocess：使用 keyring 命令进行凭据查找
• --link-mode link-mode
  当从全局缓存安装包时要使用的方

---

uv tree

显示项目的依赖树

---

使用方法

uv tree [OPTIONS]

---

选项

• --all-groups
  包含所有依赖组的依赖项。可以使用 --no-group 排除特定组。
• --allow-insecure-host allow-insecure-host
  允许与主机的不安全连接。可以多次提供。期望接收主机名（例如，localhost）、主机-端口对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：列入此列表的主机将不会与系统证书存储进行验证。仅在安全网络和已验证源中使用 --allow-insecure-host，因为它绕过 SSL 验证，可能会使您面临中间人攻击。也可以通过 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 将在写入终端或支持颜色的 TTY 时自动检测颜色支持。可能的值：auto：仅在输出将发送到支持颜色的终端或 TTY 时启用彩色输出always：无论检测到的环境如何，都启用彩色输出never：禁用彩色输出
• --config-file config-file
  用于配置的 uv.toml 文件的路径。虽然 uv 配置可以包含在 pyproject.toml 文件中，但在此上下文中不允许。也可以通过 UV_CONFIG_FILE 环境变量设置。
• --config-setting, -C config-setting
  要传递给 PEP 517 构建后端的设置，指定为 KEY=VALUE 对
• --default-index default-index
  默认包索引的 URL（默认：https://pypi.org/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 版本优化选择每个包的最新支持版本
• --frozen
  显示需求而不会锁定项目。如果锁定文件丢失，uv 将以错误退出。也可以通过 UV_FROZEN 环境变量设置。
• --group group
  包含指定依赖组的依赖项。可以多次提供。
• --help, -h
  显示此命令的简洁帮助
• --index index
  解析依赖项时使用的 URL，除默认索引外。接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。通过此标志提供的所有索引都优先于通过 --default-index 指定的索引（默认为 PyPI）。当提供多个 --index 标志时，较早的值优先。也可以通过 UV_INDEX 环境变量设置。
• --index-strategy index-strategy
  解析多个索引 URL 时使用的策略。默认情况下，uv 将在给定包可用性的第一个索引处停止，并将解析限制在第一个索引上存在的那些上（first-index）。这可以防止“依赖项混淆”攻击，其中攻击者可以将恶意软件包上传到替代索引下以相同的名称。也可以通过 UV_INDEX_STRATEGY 环境变量设置。可能的值：first-index：仅使用第一个索引返回给定包名称匹配的结果unsafe-first-match：在所有索引中搜索每个包名称，在转到下一个索引之前耗尽第一个索引的版本unsafe-best-match：在所有索引中搜索每个包名称，优先选择找到的“最佳”版本。如果包版本在多个索引中，则仅查看第一个索引的条目
• --index-url, -i index-url
  （已弃用：使用 --default-index 代替）Python 包索引的 URL（默认：https://pypi.org/simple）。接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。此标志给出的索引比通过 --extra-index-url 指定的所有其他索引的优先级低。也可以通过 UV_INDEX_URL 环境变量设置。
• --invert
  显示给定包的反向依赖项。此标志将反转树并显示依赖于给定包的包
• --keyring-provider keyring-provider
  尝试使用 keyring 进行索引 URL 的身份验证。目前，仅支持 --keyring-provider subprocess，它配置 uv 使用 keyring CLI 来处理身份验证。默认为 disabled。也可以通过 UV_KEYRING_PROVIDER 环境变量设置。可能的值：disabled：不使用 keyring 进行凭据查找subprocess：使用 `key

---

uv 工具

运行和安装由 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 工具运行

运行由 Python 包提供的命令。

默认情况下，安装的包名称假定为命令名称。

命令名称可以包含一个精确的版本，格式为 <package>@<version>，例如，uv tool run ruff@0.3.0。如果需要更复杂的版本指定或命令由不同的包提供，请使用 --from。

可以使用 uvx 来调用 Python，例如，使用 uvx python 或 uvx python@<version>。Python 解释器将在一个隔离的虚拟环境中启动。

如果工具之前已安装，即通过 uv tool install 安装，除非请求特定版本或使用 --isolated 标志，否则将使用已安装的版本。

uvx 是 uv tool run 的便利别名，它们的行为是相同的。

如果没有提供命令，将显示已安装的工具。

包将安装到 uv 缓存目录中的临时虚拟环境中。

---

使用方法

uv tool run [OPTIONS] [COMMAND]

---

选项

• --allow-insecure-host allow-insecure-host
  允许对主机的不安全连接。可以多次提供。期望接收主机名（例如，localhost）、主机端口对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：列入此列表的主机将不会与系统证书存储进行验证。仅在安全网络和已验证的源中使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您面临中间人攻击。也可以通过 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 将在写入终端或支持颜色的 TTY 时自动检测颜色支持。可能的值：auto：仅在输出将发送到终端或支持颜色的 TTY 时启用彩色输出；always：无论检测到的环境如何，都启用彩色输出；never：禁用彩色输出
• --compile-bytecode
  在安装后编译 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, -C config-setting
  以 KEY=VALUE 对的形式传递给 PEP 517 构建后端的设置
• --constraints, -c constraints
  使用给定的需求文件约束版本。约束文件类似于 requirements.txt 的文件，它仅控制要安装的依赖项的 版本。但是，将包包含在约束文件中 不会 触发该包的安装。这与 pip 的 --constraint 选项等效。也可以通过 UV_CONSTRAINT 环境变量设置。
• --default-index default-index
  默认包索引的 URL（默认：https://pypi.org/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 版本优化选择每个包的最新支持版本
• --from from
  使用给定的包提供命令。默认情况下，包名称假定与命令名称匹配。
• --help, -h
  显示此命令的简明帮助
• --index index
  解析依赖项时使用的 URL，除了默认索引之外。接受符合 PEP 503（简单存储库 API）的存储库，或布局相同的本地目录。通过此标志提供的所有索引都高于通过 --default-index 标志指定的索引（默认为 PyPI）。当提供多个 --index 标志时，较早的值具有优先级。也可以通过 UV_INDEX 环境变量设置。
• --index-strategy index-strategy
  解析多个索引 URL 时使用的策略。默认情况下，uv 将在给定包可用时的第一个索引上停止，并将解析限制在该第一个索引上（first-index）。这可以防止“依赖项混淆”攻击，攻击者可以在备用索引中上传具有相同名称的恶意包。也可以通过 UV_INDEX_STRATEGY 环境变量设置。可能的值：first-index：仅使用第一个索引返回给定包名称的结果；unsafe-first-match：在所有索引中搜索每个包名称，在移动到下一个索引之前耗尽第一个索引的版本；unsafe-best-match：在所有索引中搜索每个包名称，优先考虑找到的“最佳”版本。如果包版本在多个索引中，则仅查看第一个索引的条目
• --index-url, -i index-url
  （已弃用：使用 --default-index 代替）Python 包索引的 URL（默认：https://pypi.org/simple）。接受符合 PEP 503（简单存储库 API）的存储库，或布局相同的本地目录。此标志提供的索引比通过 --extra-index-url 标志指定的所有其他索引具有较低优先级。也可以通过 UV_INDEX_URL 环境变量设置。
• --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 复制（即 Copy-on-Write）包到 site-packages 目录；copy：从 wheel 复制包到 site-packages 目录；hardlink：从 wheel 创建到 site-packages 目录的硬链接；symlink：从 wheel 创建到 site-packages 目录的符号链接
• --managed-python
  要求使用 uv-managed Python 版本。默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv-managed Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。也可以通过 UV_MANAGED_PYTHON 环境变量设置。
• --native-tls
  是否从平台的本地证书存储加载 TLS 证书。默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。webpki-roots 是来自 Mozilla 的可靠的一组信任根，将其包含在 uv 中可以提高可移植性和性能（尤其是在 macOS 上）。但是，在某些情况下，您可能想使用平台的本地证书存储，尤其是如果您依赖于包含在系统证书存储中的企业信任根（例如，强制代理），则可以在此处使用。也可以通过 UV_NATIVE_TLS 环境变量设置。
• --no-binary
  不要安装预构建的 wheel。给定的包将从头开始构建和安装。解析器仍会使用可用的预构建 wheel 来提取包元数据。也可以通过 UV_NO_BINARY 环境变量设置。
• --no-binary-package no-binary-package
  不要为特定包安装预构建的 wheel。也可以通过 UV_NO_BINARY_PACKAGE 环境变量设置。
• --no-build
  不要构建源分发。当启用时，解析将不会运行任意 Python 代码。将重用已构建源分发的缓存的 wheel，但需要构建分发的操作将因错误而退出。也可以通过 UV_NO_BUILD 环境变量设置。
• --no-build-isolation
  禁用构建源分发时的隔离。假设已安装 PEP 518 指定的构建依赖项。也可以通过 UV_NO_BUILD_ISOLATION 环境变量设置。
• --no-build-isolation-package no-build-isolation-package
  构建源分发时禁用特定包的隔离。假设已安装该包的 PEP 518 指定的构建依赖项。
• --no-build-package no-build-package
  不要为特定包构建源分发。也可以通过 UV_NO_BUILD_PACKAGE 环境变量设置。
• --no-cache, -n
  避免从缓存中读取或写入，而是在整个操作期间使用临时目录。也可以通过 UV_NO_CACHE 环境变量设置。
• --no-config
  避免发现配置文件（pyproject.toml、uv.toml）。通常，配置文件会在当前目录、父目录或用户配置目录中找到。也可以通过 UV_NO_CONFIG 环境变量设置。
• --no-index
  忽略注册表索引（例如，PyPI），而是依赖于直接 URL 依赖项和通过 --find-links 提供的依赖项
• --no-managed-python
  禁用 uv-managed Python 版本的使用。相反，uv 将在系统上搜索合适的 Python 版本。也可以通过 UV_NO_MANAGED_PYTHON 环境变量设置。
• --no-progress
  隐藏所有进度输出。例如，旋转器或进度条。也可以通过 UV_NO_PROGRESS 环境变量设置。
• --no-python-downloads
  禁止自动下载 Python。
• [--no-sources](https://docs.astral.sh/uv/reference/cli/#uv-tool-run–no-s

---

uv 工具安装

安装由 Python 包提供的安装命令。

包将被安装到 uv 工具目录下的独立虚拟环境中。可执行文件将被链接到工具可执行目录，该目录根据 XDG 标准 确定，可以使用 uv tool dir --bin 获取。

如果工具之前已安装，现有工具通常将被替换。

---

使用方法

uv tool install [OPTIONS] <PACKAGE>

---

参数

• PACKAGE
  要安装命令的包

---

选项

• --allow-insecure-host allow-insecure-host
  允许对主机的不安全连接。可以多次提供。期望接收主机名（例如，localhost）、主机-端口对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：列入此列表的主机将不会与系统的证书存储进行验证。仅在安全网络和已验证的源中使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您面临中间人攻击。也可以通过 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 将在写入终端或 TTY 时自动检测对颜色的支持。可能的值：auto：仅在输出将发送到支持颜色的终端或 TTY 时启用彩色输出；always：无论检测到的环境如何，都启用彩色输出；never：禁用彩色输出
• --compile-bytecode
  在安装后编译 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, -C config-setting
  以 KEY=VALUE 对的形式传递给 PEP 517 构建后端的设置
• --constraints, -c constraints
  使用给定的需求文件约束版本。约束文件类似于 requirements.txt 的文件，它仅控制要安装的依赖项的 版本。但是，将包包含在约束文件中将 不会 触发该包的安装。这与 pip 的 --constraint 选项等效。也可以通过 UV_CONSTRAINT 环境变量设置。
• --default-index default-index
  默认包索引的 URL（默认：https://pypi.org/simple）。接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式排列的本地目录。此标志给出的索引比通过 --index 标志指定的所有其他索引的优先级低。也可以通过 UV_DEFAULT_INDEX 环境变量设置。
• --directory directory
  在运行命令之前切换到指定的目录。相对路径将与给定的目录一起解析。有关仅更改项目根目录的信息，请参阅 --project。也可以通过 UV_DIRECTORY 环境变量设置。
• --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）的存储库，或以相同格式排列的本地目录。通过此标志提供的所有索引都比通过 --extra-index-url 标志指定的索引的优先级高。当提供多个 --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 标志指定的索引的优先级高。当提供多个 --index 标志时，早期值优先。也可以通过 UV_INDEX 环境变量设置。
• --index-strategy index-strategy
  在解析多个索引 URL 时使用的策略。默认情况下，uv 将在找到给定包的第一个索引时停止，并将解析限制在该第一个索引上存在的那些上（first-index）。这可以防止“依赖项混淆”攻击，攻击者可以在替代索引中上传具有相同名称的恶意包。也可以通过 UV_INDEX_STRATEGY 环境变量设置。可能的值：first-index：仅使用第一个返回给定包名称匹配的第一个索引的结果；unsafe-first-match：在所有索引中搜索每个包名称，在移动到下一个索引之前耗尽第一个索引的版本；unsafe-best-match：在所有索引中搜索每个包名称，优先考虑找到的“最佳”版本。如果包版本在多个索引中，则仅查看第一个索引的条目
• --index-url, -i index-url
  （已弃用：使用 --default-index 代替）Python 包索引的 URL（默认：https://pypi.org/simple）。接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式排列的本地目录。此标志给出的索引比通过 --extra-index-url 标志指定的索引的优先级低。也可以通过 UV_INDEX_URL 环境变量设置。
• --keyring-provider keyring-provider
  尝试使用 keyring 对索引 URL 进行身份验证。目前，仅支持 --keyring-provider subprocess，它配置 uv 使用 keyring CLI 来处理身份验证。默认为 disabled。也可以通过 UV_KEYRING_PROVIDER 环境变量设置。可能的值：disabled：不要使用 keyring 进行凭据查找；subprocess：使用 keyring 命令进行凭据查找
• --link-mode link-mode
  在从全局缓存安装包时使用的方法。默认为 macOS 上的克隆（也称为 Copy-on-Write），Linux 和 Windows 上的硬链接。也可以通过 UV_LINK_MODE 环境变量设置。可能的值：clone：从 wheel 克隆（即复制-on-write）包到 site-packages 目录；copy：将包从 wheel 复制到 site-packages 目录；hardlink：从 wheel 硬链接包到 site-packages 目录；symlink：将包从 wheel 符号链接到 site-packages 目录
• --managed-python
  要求使用 uv-managed Python 版本。默认情况下，uv 优先使用它管理的 Python 版本。如果没有安装 uv-managed Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。也可以通过 UV_MANAGED_PYTHON 环境变量设置。
• --native-tls
  是否从平台的本地证书存储加载 TLS 证书。默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。webpki-roots 是来自 Mozilla 的可靠的一组信任根，将其包含在 uv 中可以提高可移植性和性能（尤其是在 macOS 上）。但是，在某些情况下，您可能想使用平台的本地证书存储，特别是如果您依赖于包含在系统证书存储中的企业信任根（例如，强制代理），则更是如此。也可以通过 UV_NATIVE_TLS 环境变量设置。
• --no-binary
  不要安装预构建的 wheel。给定的包将从头开始构建和安装。解析器仍会使用可用的预构建 wheel 来提取包元数据，如果有的话。也可以通过 UV_NO_BINARY 环境变量设置。
• --no-binary-package no-binary-package
  不要为特定包安装预构建的 wheel。也可以通过 UV_NO_BINARY_PACKAGE 环境变量设置。
• --no-build
  不要构建源分发。当启用时，解析将不会运行任意 Python 代码。将重用已构建源分发的缓存的 wheel，但需要构建分发的操作将因错误而退出。也可以通过 UV_NO_BUILD 环境变量设置。
• --no-build-isolation
  禁用构建源分发时的隔离。假设 PEP 518 中指定的构建依赖项已安装。也可以通过 UV_NO_BUILD_ISOLATION 环境变量设置。
• --no-build-isolation-package no-build-isolation-package
  在构建特定包的源分发时禁用隔离。假设包的 PEP 518 中指定的构建依赖项已安装。
• --no-build-package no-build-package
  不要为特定包构建源分发。也可以通过 UV_NO_BUILD_PACKAGE 环境变量设置。
• --no-cache, -n
  避免从缓存中读取或写入，而是在整个操作期间使用临时目录。也可以通过 UV_NO_CACHE 环境变量设置。
• --no-config
  避免发现配置文件（pyproject.toml、uv.toml）。通常，配置文件会在当前目录、父目录或用户配置目录中查找。也可以通过 UV_NO_CONFIG 环境变量设置。
• --no-index
  忽略注册表索引（例如，PyPI），而是依赖于直接 URL 依赖项和通过 --find-links 提供的依赖项。
• --no-managed-python
  禁用 uv-managed Python 版本的使用。相反，uv 将在系统上搜索合适的 Python 版本。也可以通过 UV_NO_MANAGED_PYTHON 环境变量设置。
• --no-progress
  隐藏所有进度输出。例如，旋转器或进度条。也可以通过 UV_NO_PROGRESS 环境变量设置。
• --no-python-downloads
  禁用 Python 的自动下载。
• --no-sources
  忽略 tool.uv.sources 表

---

uv 工具升级

升级已安装的工具。

如果一个工具是带有版本约束安装的，升级时会尊重这些约束——要升级超过最初提供的约束的工具，请再次使用 uv tool install。

如果一个工具是带有特定设置的安装的，升级时会尊重这些设置。例如，如果在安装期间提供了 --prereleases allow，它将在升级中继续被尊重。

---

使用方法

uv tool upgrade [OPTIONS] <NAME>...

---

参数

• NAME
  要升级的工具的名称，以及可选的版本指定符

---

选项

• --all
  升级所有工具
• --allow-insecure-host allow-insecure-host
  允许到主机的非安全连接。可以多次提供。期望接收主机名（例如，localhost）、主机-端口号对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：列表中包含的主机将不会与系统证书存储进行验证。仅在安全网络和已验证的来源中使用 --allow-insecure-host，因为它绕过 SSL 验证，可能会使您面临中间人攻击。也可以使用 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 将自动检测终端或 TTY 支持颜色写入时启用颜色输出。可能的值：auto：仅在输出将发送到具有颜色支持终端或 TTY 时启用颜色输出always：无论检测到的环境如何都启用颜色输出never：禁用颜色输出
• --compile-bytecode
  安装后编译 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, -C config-setting
  以 KEY=VALUE 对的形式传递给 PEP 517 构建后端的设置
• --default-index default-index
  默认包索引的 URL（默认：https://pypi.org/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 标志时，较早的值具有优先级。也可以使用 UV_INDEX 环境变量设置。
• --index-strategy index-strategy
  解析多个索引 URL 时使用的策略。默认情况下，uv 将在给定包可用性的第一个索引处停止，并将解析限制在第一个索引上存在的那些上（first-index）。这防止了“依赖混淆”攻击，攻击者可以在备用索引中上传具有相同名称的恶意包。也可以使用 UV_INDEX_STRATEGY 环境变量设置。可能的值：first-index：仅使用第一个索引返回给定包名称的匹配项的结果unsafe-first-match：搜索所有索引中的每个包名称，在移动到下一个索引之前耗尽第一个索引中的版本unsafe-best-match：搜索所有索引中的每个包名称，优先选择找到的“最佳”版本。如果包版本在多个索引中，则仅查看第一个索引的条目
• --index-url, -i index-url
  （已弃用：使用 --default-index 代替）Python 包索引的 URL（默认：https://pypi.org/simple）。接受符合 PEP 503 的存储库（简单存储库 API），或以相同格式布局的本地目录。此标志提供的索引的优先级低于通过 --extra-index-url 标志指定的所有索引。也可以使用 UV_INDEX_URL 环境变量设置。
• --keyring-provider keyring-provider
  尝试使用 keyring 进行索引 URL 的身份验证。目前，仅支持 --keyring-provider subprocess，它配置 uv 使用 keyring CLI 来处理身份验证。默认为 disabled。也可以使用 UV_KEYRING_PROVIDER 环境变量设置。可能的值：disabled：不使用 keyring 进行凭据查找subprocess：使用 keyring 命令进行凭据查找
• --link-mode link-mode
  从全局缓存安装包时使用的方法。默认情况下，在 macOS 上为 clone（也称为 Copy-on-Write），在 Linux 和 Windows 上为 hardlink。也可以使用 UV_LINK_MODE 环境变量设置。可能的值：clone：从 wheel 复制（即复制-on-write）包到 site-packages 目录copy：从 wheel 复制包到 site-packages 目录hardlink：从 wheel 创建硬链接到 site-packages 目录symlink：从 wheel 创建符号链接到 site-packages 目录
• --managed-python
  要求使用 uv-managed Python 版本。默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv-managed Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。也可以使用 UV_MANAGED_PYTHON 环境变量设置。
• --native-tls
  是否从平台的本地证书存储加载 TLS 证书。默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。webpki-roots 是来自 Mozilla 的可靠信任根集，将其包含在 uv 中可以提高可移植性和性能（尤其是在 macOS 上）。但是，在某些情况下，您可能想使用平台的本地证书存储，尤其是如果您依赖于包含在系统证书存储中的企业信任根（例如，强制代理），则可能想使用它。也可以使用 UV_NATIVE_TLS 环境变量设置。
• --no-binary
  不安装预构建的 wheel。给定的包将从头开始构建和安装。解析器仍将使用可用的预构建 wheel 来提取包元数据。也可以使用 UV_NO_BINARY 环境变量设置。
• --no-binary-package no-binary-package
  不为特定包安装预构建的 wheel。也可以使用 UV_NO_BINARY_PACKAGE 环境变量设置。
• --no-build
  不构建源分发。当启用时，解析将不会运行任意 Python 代码。将重用已构建源分发的缓存的 wheel，但需要构建分发的操作将因错误而退出。也可以使用 UV_NO_BUILD 环境变量设置。
• --no-build-isolation
  禁用构建源分发时的隔离。假设已安装 PEP 518 规范中指定的构建依赖项。也可以使用 UV_NO_BUILD_ISOLATION 环境变量设置。
• --no-build-isolation-package no-build-isolation-package
  在构建特定包的源分发时禁用隔离。假设已安装包的 PEP 518 规范中指定的构建依赖项。
• --no-build-package no-build-package
  不为特定包构建源分发。也可以使用 UV_NO_BUILD_PACKAGE 环境变量设置。
• --no-cache, -n
  避免从缓存中读取或写入，而是在操作期间使用临时目录。也可以使用 UV_NO_CACHE 环境变量设置。
• --no-config
  避免发现配置文件（pyproject.toml、uv.toml）。通常，配置文件会在当前目录、父目录或用户配置目录中找到。也可以使用 UV_NO_CONFIG 环境变量设置。
• --no-index
  忽略注册索引（例如，PyPI），而是依赖于直接 URL 依赖项和通过 --find-links 提供的依赖项。
• --no-managed-python
  禁用 uv-managed Python 版本的使用。相反，uv 将在系统上搜索合适的 Python 版本。也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。
• --no-progress
  隐藏所有进度输出。例如，旋转器或进度条。也可以使用 UV_NO_PROGRESS 环境变量设置。
• --no-python-downloads
  禁用 Python 的自动下载。
• --no-sources
  忽略 tool.uv.sources 表在解析依赖项时。用于锁定对符合标准、可发布的包元数据的依赖，而不是使用任何工作区、Git、URL 或本地路径源
• --offline
  禁用网络访问。当禁用时，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 接口中使用时没有效果。
• --python, -p python
  升级工具，并指定使用给定的 Python 解释器构建其环境。与 --all 结合使用以应用于所有工具。有关 Python 发现和受支持的请求格式的详细信息，请参阅 uv python。
• --quiet, -q
  不打印任何输出
• --reinstall
  重新安装所有包，无论它们是否已经安装。意味着 --refresh
• --reinstall-package reinstall-package
  重新安装特定包，无论它是否已经安装。意味着 --refresh-package
• --resolution resolution
  选择给定包

---

uv 工具列表

工具列表

---

使用方法

uv tool list [OPTIONS]

---

选项

• --allow-insecure-host allow-insecure-host
  允许与主机的不安全连接。可以多次提供。期望接收主机名（例如，localhost）、主机-端口对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：列入此列表的主机将不会与系统的证书存储进行验证。仅在安全网络和已验证的源中使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您面临中间人攻击。也可以通过 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。此设置在 uv pip 接口中使用时没有效果。
• --help, -h
  显示此命令的简洁帮助信息
• --managed-python
  要求使用 uv-managed Python 版本。默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv-managed Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。也可以通过 UV_MANAGED_PYTHON 环境变量设置。
• --native-tls
  是否从平台的本地证书存储加载 TLS 证书。默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。webpki-roots 是来自 Mozilla 的可靠信任根集合，将其包含在 uv 中可以提高可移植性和性能（尤其是在 macOS 上）。但是，在某些情况下，您可能希望使用平台的本地证书存储，特别是如果您依赖于包含在系统证书存储中的企业信任根（例如，强制代理），则更是如此。也可以通过 UV_NATIVE_TLS 环境变量设置。
• --no-cache, -n
  避免从缓存中读取或写入，而是在操作期间使用临时目录。也可以通过 UV_NO_CACHE 环境变量设置。
• --no-config
  避免发现配置文件（pyproject.toml、uv.toml）。通常，配置文件会在当前目录、父目录或用户配置目录中找到。也可以通过 UV_NO_CONFIG 环境变量设置。
• --no-managed-python
  禁用 uv-managed Python 版本的使用。相反，uv 将在系统上搜索合适的 Python 版本。也可以通过 UV_NO_MANAGED_PYTHON 环境变量设置。
• --no-progress
  隐藏所有进度输出。例如，旋转器或进度条。也可以通过 UV_NO_PROGRESS 环境变量设置。
• --offline
  禁用网络访问。当禁用时，uv 将仅使用本地缓存的数据和本地可用的文件。也可以通过 UV_OFFLINE 环境变量设置。
• --project project
  在给定的项目目录中运行命令。所有 pyproject.toml、uv.toml 和 .python-version 文件将通过从项目根目录向上遍历目录树来发现，项目虚拟环境（.venv）也是如此。其他命令行参数（如相对路径）将以当前工作目录为基准解析。有关完全更改工作目录的信息，请参阅 --directory。此设置在 uv pip 接口中使用时没有效果。
• --quiet, -q
  不打印任何输出
• --show-paths
  是否显示每个工具环境和已安装可执行文件的路径
• --show-version-specifiers
  是否显示用于安装每个工具的版本指定符
• --verbose, -v
  使用详细输出。您可以使用 RUST_LOG 环境变量配置细粒度日志记录。（https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives）
• --version, -V
  显示 uv 版本

---

uv 工具卸载

卸载一个工具

---

使用方法

uv tool uninstall [OPTIONS] <NAME>...

---

参数

• NAME
  要卸载的工具名称

---

选项

• --all
  卸载所有工具
• --allow-insecure-host allow-insecure-host
  允许与主机的不安全连接。可以多次提供。预期接收主机名（例如，localhost）、主机-端口号对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：包含在此列表中的主机将不会与系统证书存储进行验证。仅在安全网络和已验证的源中使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您面临中间人攻击。也可以通过 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 将在写入终端或 TTY 支持颜色时自动检测颜色支持。可能的值：auto：仅在输出将发送到支持颜色的终端或 TTY 时启用彩色输出always：无论检测到的环境如何，都启用彩色输出never：禁用彩色输出
• --config-file config-file
  要使用的 uv.toml 文件的路径。虽然 uv 配置可以包含在 pyproject.toml 文件中，但在此上下文中不允许。也可以通过 UV_CONFIG_FILE 环境变量设置。
• --directory directory
  在运行命令之前切换到指定的目录。相对路径将使用给定的目录作为基础。有关仅更改项目根目录的信息，请参阅 --project。见 --directory 以完全更改工作目录。此设置在 uv pip 接口中使用时没有效果。
• --help, -h
  显示此命令的简洁帮助信息
• --managed-python
  要求使用 uv-managed Python 版本。默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv-managed Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。也可以通过 UV_MANAGED_PYTHON 环境变量设置。
• --native-tls
  是否从平台的本地证书存储加载 TLS 证书。默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。webpki-roots 是来自 Mozilla 的可靠信任根集合，将其包含在 uv 中可以提高可移植性和性能（尤其是在 macOS 上）。但是，在某些情况下，您可能想使用平台的本地证书存储，特别是如果您依赖于包含在系统证书存储中的企业信任根（例如，强制代理），则更是如此。也可以通过 UV_NATIVE_TLS 环境变量设置。
• --no-cache, -n
  避免从缓存中读取或写入，而是在整个操作期间使用临时目录。也可以通过 UV_NO_CACHE 环境变量设置。
• --no-config
  避免发现配置文件（pyproject.toml、uv.toml）。通常，配置文件会发现在当前目录、父目录或用户配置目录中。也可以通过 UV_NO_CONFIG 环境变量设置。
• --no-managed-python
  禁用 uv-managed Python 版本的使用。相反，uv 将在系统上搜索合适的 Python 版本。也可以通过 UV_NO_MANAGED_PYTHON 环境变量设置。
• --no-progress
  隐藏所有进度输出。例如，旋转器或进度条。也可以通过 UV_NO_PROGRESS 环境变量设置。
• --no-python-downloads
  禁用 Python 的自动下载。
• --offline
  禁用网络访问。当禁用时，uv 将仅使用本地缓存的数据和本地可用的文件。也可以通过 UV_OFFLINE 环境变量设置。
• --project project
  在给定的项目目录中运行命令。所有 pyproject.toml、uv.toml 和 .python-version 文件将通过从项目根目录向上遍历目录树来发现，以及项目的虚拟环境（.venv）。其他命令行参数（如相对路径）将相对于当前工作目录解析。有关完全更改工作目录的信息，请参阅 --directory。此设置在 uv pip 接口中使用时没有效果。
• --quiet, -q
  不打印任何输出
• --verbose, -v
  使用详细输出。您可以使用 RUST_LOG 环境变量配置细粒度日志记录。（https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives）
• --version, -V
  显示 uv 版本

---

uv 工具更新 shell

确保工具的可执行目录在 PATH 上。

如果工具的可执行目录不在 PATH 上，uv 将尝试将其添加到相关的 shell 配置文件中。

如果 shell 配置文件已经包含将可执行目录添加到路径的说明，但目录不在 PATH 上，uv 将以错误退出。

工具的可执行目录根据 XDG 标准 确定，可以使用 uv tool dir --bin 获取。

---

使用方法

uv tool update-shell [OPTIONS]

---

选项

• --allow-insecure-host allow-insecure-host
  允许与主机的不安全连接。可以多次提供。期望接收主机名（例如，localhost）、主机-端口对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：列入此列表的主机将不会与系统的证书存储进行验证。仅在安全网络且来源已验证的情况下使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您面临中间人攻击。也可以通过 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
  显示此命令的简洁帮助信息
• --managed-python
  要求使用 uv-managed Python 版本。默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv-managed Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。也可以通过 UV_MANAGED_PYTHON 环境变量设置。
• --native-tls
  是否从平台的本机证书存储加载 TLS 证书。默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。webpki-roots 是来自 Mozilla 的可靠信任根集，将其包含在 uv 中可以提高可移植性和性能（尤其是在 macOS 上）。但是，在某些情况下，您可能想使用平台的本机证书存储，特别是如果您依赖系统证书存储中包含的企业信任根（例如，强制代理），则可能更想使用它。也可以通过 UV_NATIVE_TLS 环境变量设置。
• --no-cache, -n
  避免从缓存中读取或写入，而是在整个操作期间使用临时目录。也可以通过 UV_NO_CACHE 环境变量设置。
• --no-config
  避免发现配置文件（pyproject.toml、uv.toml）。通常，配置文件会在当前目录、父目录或用户配置目录中找到。也可以通过 UV_NO_CONFIG 环境变量设置。
• --no-managed-python
  禁用 uv-managed Python 版本的使用。相反，uv 将在系统上搜索合适的 Python 版本。也可以通过 UV_NO_MANAGED_PYTHON 环境变量设置。
• --no-progress
  隐藏所有进度输出。例如，旋转器或进度条。也可以通过 UV_NO_PROGRESS 环境变量设置。
• --no-python-downloads
  禁用 Python 的自动下载。
• --offline
  禁用网络访问。当禁用时，uv 将仅使用本地缓存的数据和本地可用的文件。也可以通过 UV_OFFLINE 环境变量设置。
• --project project
  在给定的项目目录中运行命令。所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历目录树来发现，项目虚拟环境（.venv）也是如此。其他命令行参数（如相对路径）将以当前工作目录为基准进行解析。有关完全更改工作目录的信息，请参阅 --directory。此设置在 uv pip 接口中使用时没有效果。
• --quiet, -q
  不打印任何输出
• --verbose, -v
  使用详细输出。您可以使用 RUST_LOG 环境变量配置细粒度日志记录。（https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives）
• --version, -V
  显示 uv 版本

---

uv 工具目录

显示 uv 工具目录的路径。

工具目录用于存储已安装工具的环境和元数据。

默认情况下，工具存储在 Unix 系统中的 uv 数据目录 $XDG_DATA_HOME/uv/tools 或 $HOME/.local/share/uv/tools，以及在 Windows 中的 %APPDATA%\uv\data\tools。

工具安装目录可以通过 $UV_TOOL_DIR 覆盖。

要查看 uv 安装可执行文件的目录，请使用 --bin 标志。

---

使用方法

uv tool dir [OPTIONS]

---

选项

• --allow-insecure-host allow-insecure-host
  允许与主机的不安全连接。可以多次提供。预期接收主机名（例如，localhost）、主机-端口对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：此列表中的主机将不会与系统的证书存储进行验证。仅在安全网络和已验证的源中使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您面临中间人攻击。也可以通过 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
  显示此命令的简洁帮助信息
• --managed-python
  要求使用 uv-managed Python 版本。默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv-managed Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。也可以通过 UV_MANAGED_PYTHON 环境变量设置。
• --native-tls
  是否从平台的本地证书存储中加载 TLS 证书。默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。webpki-roots 是来自 Mozilla 的可靠的一组信任根，将它们包含在 uv 中可以提高可移植性和性能（尤其是在 macOS 上）。但是，在某些情况下，您可能希望使用平台的本地证书存储，特别是如果您依赖的是包含在系统证书存储中的企业信任根（例如，强制代理），则更是如此。也可以通过 UV_NATIVE_TLS 环境变量设置。
• --no-cache, -n
  避免从缓存中读取或写入，而是在操作期间使用临时目录。也可以通过 UV_NO_CACHE 环境变量设置。
• --no-config
  避免发现配置文件（pyproject.toml、uv.toml）。通常，配置文件会在当前目录、父目录或用户配置目录中找到。也可以通过 UV_NO_CONFIG 环境变量设置。
• --no-managed-python
  禁用 uv-managed Python 版本的使用。相反，uv 将在系统上搜索合适的 Python 版本。也可以通过 UV_NO_MANAGED_PYTHON 环境变量设置。
• --no-progress
  隐藏所有进度输出。例如，旋转器或进度条。也可以通过 UV_NO_PROGRESS 环境变量设置。
• --no-python-downloads
  禁用 Python 的自动下载。
• --offline
  禁用网络访问。当禁用时，uv 将仅使用本地缓存数据和本地可用的文件。也可以通过 UV_OFFLINE 环境变量设置。
• --project project
  在给定的项目目录中运行命令。所有 pyproject.toml、uv.toml 和 .python-version 文件将通过从项目根目录向上遍历来找到，同样还有项目的虚拟环境（.venv）。其他命令行参数（如相对路径）将以当前工作目录为基准解析。有关完全更改工作目录的信息，请参阅 --directory。此设置在 uv pip 接口中使用时没有效果。
• --quiet, -q
  不打印任何输出
• --verbose, -v
  使用详细输出。您可以使用 RUST_LOG 环境变量配置细粒度日志记录。（https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives）
• --version, -V
  显示 uv 版本

---

uv python

管理 Python 版本和安装

通常，uv 首先在虚拟环境中搜索 Python，无论是活动虚拟环境还是当前工作目录或任何父目录中的 .venv 目录。如果不需要虚拟环境，uv 将然后搜索 Python 解释器。Python 解释器通过在 PATH 环境变量中搜索 Python 可执行文件来找到。

在 Windows 上，还会在注册表中搜索 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> 例如 cpython@3.12
• <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 find
  搜索 Python 安装
• uv python pin
  锁定到特定 Python 版本
• uv python dir
  显示 uv Python 安装目录
• uv python uninstall
  卸载 Python 版本

---

uv python 列表

列出可用的 Python 安装版本。

默认情况下，显示已安装的 Python 版本和每个受支持的主要 Python 版本的最新可用修补版本的下载链接。

使用 --managed-python 只查看受管理的 Python 版本。

使用 --no-managed-python 忽略受管理的 Python 版本。

使用 --all-versions 查看所有可用的修补版本。

使用 --only-installed 忽略可用的下载链接。

---

使用方法

uv python list [OPTIONS]

---

选项

• --all-arches
  列出所有架构的 Python 下载。默认情况下，只显示当前架构的下载。
• --all-platforms
  列出所有平台的 Python 下载。默认情况下，只显示当前平台的下载。
• --all-versions
  列出所有 Python 版本，包括旧的补丁版本。默认情况下，对于每个次要版本，只显示最新的补丁版本。
• --allow-insecure-host allow-insecure-host
  允许与主机的不安全连接。可以多次提供。期望接收主机名（例如，localhost）、主机-端口对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：列入此列表的主机将不会与系统证书存储进行验证。仅在安全网络和已验证源中使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您面临中间人攻击。也可以通过 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。此设置在 uv pip 接口中使用时没有效果。
• --help, -h
  显示此命令的简洁帮助
• --managed-python
  要求使用 uv-managed Python 版本。默认情况下，uv 会优先使用它管理的 Python 版本。但是，如果没有安装 uv-managed Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。也可以通过 UV_MANAGED_PYTHON 环境变量设置。
• --native-tls
  是否从平台的本地证书存储中加载 TLS 证书。默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。webpki-roots 是来自 Mozilla 的可靠信任根集，将其包含在 uv 中可以提高可移植性和性能（特别是在 macOS 上）。但是，在某些情况下，您可能希望使用平台的本地证书存储，尤其是如果您依赖于包含在系统证书存储中的企业信任根（例如，强制代理），可以设置通过 UV_NATIVE_TLS 环境变量。
• --no-cache, -n
  避免从缓存中读取或写入，而是在操作期间使用临时目录。也可以通过 UV_NO_CACHE 环境变量设置。
• --no-config
  避免发现配置文件（pyproject.toml、uv.toml）。通常，配置文件会在当前目录、父目录或用户配置目录中查找。也可以通过 UV_NO_CONFIG 环境变量设置。
• --no-managed-python
  禁用 uv-managed Python 版本的使用。相反，uv 将在系统上搜索合适的 Python 版本。也可以通过 UV_NO_MANAGED_PYTHON 环境变量设置。
• --no-progress
  隐藏所有进度输出。例如，旋转器或进度条。也可以通过 UV_NO_PROGRESS 环境变量设置。
• --no-python-downloads
  禁用 Python 的自动下载。
• --offline
  禁用网络访问。当禁用时，uv 将仅使用本地缓存数据和本地可用的文件。也可以通过 UV_OFFLINE 环境变量设置。
• --only-downloads
  仅显示 Python 下载，排除已安装的分发。默认情况下，显示当前平台的可用下载。
• --only-installed
  仅显示已安装的 Python 版本，排除可用下载。默认情况下，显示当前平台的可用下载。
• --output-format output-format
  选择输出格式[默认: text]可能的值:text: 纯文本（供人类阅读）json: JSON（供计算机阅读）
• --project project
  在给定的项目目录中运行命令。所有 pyproject.toml、uv.toml 和 .python-version 文件将通过从项目根目录向上遍历目录树来发现，项目虚拟环境（.venv）也是如此。其他命令行参数（例如相对路径）将以当前工作目录为相对路径解析。有关更改整个工作目录的信息，请参阅 --directory。此设置在 uv pip 接口中使用时没有效果。
• --quiet, -q
  不打印任何输出
• --show-urls
  显示可用 Python 下载的 URL。默认情况下，这些显示为 <download available>。
• --verbose, -v
  使用详细输出。您可以使用 RUST_LOG 环境变量配置细粒度日志记录。（https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives）
• --version, -V
  显示 uv 版本

---

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 可执行文件，管理的 Python 版本仅在 uv 命令或活动虚拟环境中使用。支持实验性地将 Python 可执行文件添加到 PATH 中——使用 --preview 标志启用此行为。

可以请求多个 Python 版本。

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

---

使用方法

uv python install [OPTIONS] [TARGETS]...

---

参数

• TARGETS
  要安装的 Python 版本。如果未提供，将读取 UV_PYTHON 环境变量中的请求的 Python 版本，然后是 .python-versions 或 .python-version 文件。如果以上都没有，uv 将检查是否已安装任何 Python 版本。如果没有，它将安装最新稳定的 Python 版本。查看 uv python 了解支持请求的格式。

---

选项

• --allow-insecure-host allow-insecure-host
  允许与主机的不安全连接。可以多次提供。期望接收主机名（例如，localhost）、主机-端口号对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：此列表中的主机将不会与系统证书存储进行验证。仅在安全网络和已验证的源中使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您面临中间人攻击。也可以通过 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 将在写入终端或支持颜色的 TTY 时自动检测颜色支持。可能的值：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 安装。要查看当前的 Python 安装目录，请运行 uv python dir。默认为 ~/.local/share/uv/python。也可以通过 UV_PYTHON_INSTALL_DIR 环境变量设置。
• --managed-python
  要求使用 uv-managed Python 版本。默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv-managed 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 环境变量设置。
• --native-tls
  是否从平台的本地证书存储加载 TLS 证书。默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。webpki-roots 是来自 Mozilla 的可靠信任根集，将其包含在 uv 中可以提高可移植性和性能（尤其是在 macOS 上）。但是，在某些情况下，您可能希望使用平台的本地证书存储，特别是如果您依赖于包含在系统证书存储中的企业信任根（例如，强制代理），则更是如此。也可以通过 UV_NATIVE_TLS 环境变量设置。
• --no-cache, -n
  避免从缓存中读取或写入，而是在操作期间使用临时目录。也可以通过 UV_NO_CACHE 环境变量设置。
• --no-config
  避免发现配置文件（pyproject.toml、uv.toml）。通常，配置文件将在当前目录、父目录或用户配置目录中找到。也可以通过 UV_NO_CONFIG 环境变量设置。
• --no-managed-python
  禁用 uv-managed Python 版本的使用。相反，uv 将在系统上搜索合适的 Python 版本。也可以通过 UV_NO_MANAGED_PYTHON 环境变量设置。
• --no-progress
  隐藏所有进度输出。例如，旋转器或进度条。也可以通过 UV_NO_PROGRESS 环境变量设置。
• --no-python-downloads
  禁用 Python 的自动下载。
• --offline
  禁用网络访问。当禁用时，uv 将仅使用本地缓存数据和本地可用文件。也可以通过 UV_OFFLINE 环境变量设置。
• --project project
  在指定的项目目录中运行命令。所有 pyproject.toml、uv.toml 和 .python-version 文件将通过从项目根目录向上遍历目录树来发现，以及项目的虚拟环境（.venv）。其他命令行参数（如相对路径）将以当前工作目录为相对路径解析。有关完全更改工作目录的信息，请参阅 --directory。此设置在 uv pip 接口中使用时没有效果。
• --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 环境变量设置。
• --quiet, -q
  不打印任何输出
• --reinstall, -r
  如果已安装，重新安装请求的 Python 版本。默认情况下，如果已安装版本，uv 将成功退出。
• --verbose, -v
  使用详细输出。您可以使用 RUST_LOG 环境变量配置细粒度日志记录。（https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives）
• --version, -V
  显示 uv 版本

---

uv python find

搜索 Python 安装。

显示 Python 可执行文件的路径。

查看 uv help python 以了解支持的请求格式和发现行为的详细信息。

---

使用方法

uv python find [OPTIONS] [REQUEST]

---

参数

• REQUEST
  Python 请求。查看支持的请求格式，请参阅 uv python。

---

选项

• --allow-insecure-host allow-insecure-host
  允许对主机的不安全连接。可以多次提供。期望接收主机名（例如，localhost）、主机-端口对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：列表中包含的主机将不会与系统的证书存储进行验证。仅在安全网络和已验证的源中使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您面临中间人攻击。也可以通过 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
  显示此命令的简洁帮助信息
• --managed-python
  要求使用 uv-managed Python 版本。默认情况下，uv 倾向于使用它管理的 Python 版本。但是，如果没有安装 uv-managed Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。也可以通过 UV_MANAGED_PYTHON 环境变量设置。
• --native-tls
  是否从平台的本地证书存储加载 TLS 证书。默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。webpki-roots 是来自 Mozilla 的可靠的一组信任根，将它们包含在 uv 中可以提高可移植性和性能（尤其是在 macOS 上）。但是，在某些情况下，您可能希望使用平台的本地证书存储，尤其是如果您依赖于包含在系统证书存储中的企业信任根（例如，强制代理）时。也可以通过 UV_NATIVE_TLS 环境变量设置。
• --no-cache, -n
  避免从缓存中读取或写入，而是在操作期间使用临时目录。也可以通过 UV_NO_CACHE 环境变量设置。
• --no-config
  避免发现配置文件（pyproject.toml、uv.toml）。通常，配置文件会在当前目录、父目录或用户配置目录中找到。也可以通过 UV_NO_CONFIG 环境变量设置。
• --no-managed-python
  禁用 uv-managed Python 版本的使用。相反，uv 将在系统上搜索合适的 Python 版本。也可以通过 UV_NO_MANAGED_PYTHON 环境变量设置。
• --no-progress
  隐藏所有进度输出。例如，旋转器或进度条。也可以通过 UV_NO_PROGRESS 环境变量设置。
• --no-project
  避免发现项目或工作区。否则，当没有提供请求时，将使用当前目录或父目录中项目的 Python 依赖项。
• --no-python-downloads
  禁用 Python 的自动下载。
• --offline
  禁用网络访问。当禁用时，uv 只会使用本地缓存的数据和本地可用的文件。也可以通过 UV_OFFLINE 环境变量设置。
• --project project
  在给定的项目目录中运行命令。所有 pyproject.toml、uv.toml 和 .python-version 文件将通过从项目根目录向上遍历目录树来发现，以及项目的虚拟环境（.venv）。其他命令行参数（如相对路径）将相对于当前工作目录进行解析。有关完全更改工作目录的信息，请参阅 --directory。在 uv pip 接口中使用此设置时，此设置没有效果。
• --quiet, -q
  不打印任何输出
• --system
  仅查找系统 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）
• --version, -V
  显示 uv 版本

---

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 版本请求 request.uv 支持比其他读取 .python-version 文件的工具（如 pyenv）更多的格式，即 pyenv。如果需要与这些工具兼容，请仅使用版本号而不是复杂的请求，例如 cpython@3.10。如果没有提供请求，将显示当前已固定的版本。有关支持的请求格式，请参阅 uv python。

---

选项

• --allow-insecure-host allow-insecure-host
  允许与主机的不安全连接。可以多次提供。预期接收主机名（例如，localhost）、主机端口对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：此列表中包含的主机将不会与系统的证书存储进行验证。仅在安全网络中带有验证源的情况下使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您容易受到中间人攻击。也可以使用 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 版本固定时，将使用此版本。与本地版本固定不同，此版本用作更改全局状态的命令（如 uv tool install）的默认值。
• --help, -h
  显示此命令的简洁帮助信息
• --managed-python
  要求使用 uv-managed Python 版本。默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv-managed Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。也可以使用 UV_MANAGED_PYTHON 环境变量设置。
• --native-tls
  是否从平台的本地证书存储加载 TLS 证书。默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。webpki-roots 是来自 Mozilla 的可靠信任根集，将其包含在 uv 中可以提高可移植性和性能（尤其是在 macOS 上）。但是，在某些情况下，您可能希望使用平台的本地证书存储，尤其是如果您依赖于包含在系统证书存储中的企业信任根（例如，强制代理），则更是如此。也可以使用 UV_NATIVE_TLS 环境变量设置。
• --no-cache, -n
  避免从缓存中读取或写入，而是在操作期间使用临时目录。也可以使用 UV_NO_CACHE 环境变量设置。
• --no-config
  避免发现配置文件（pyproject.toml、uv.toml）。通常，配置文件会在当前目录、父目录或用户配置目录中找到。也可以使用 UV_NO_CONFIG 环境变量设置。
• --no-managed-python
  禁用 uv-managed Python 版本的使用。相反，uv 将在系统上搜索合适的 Python 版本。也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。
• --no-progress
  隐藏所有进度输出。例如，旋转器或进度条。也可以使用 UV_NO_PROGRESS 环境变量设置。
• --no-project
  避免验证 Python 固定与项目或工作空间兼容。默认情况下，项目或工作空间会在当前目录或任何父目录中找到。如果找到工作空间，则将 Python 固定与工作空间的 requires-python 约束进行验证。
• --no-python-downloads
  禁用 Python 的自动下载。
• --offline
  禁用网络访问。当禁用时，uv 将仅使用本地缓存数据和本地可用的文件。也可以使用 UV_OFFLINE 环境变量设置。
• --project project
  在给定的项目目录中运行命令。所有 pyproject.toml、uv.toml 和 .python-version 文件将通过从项目根目录向上遍历目录树来找到，同样还有项目的虚拟环境（.venv）。其他命令行参数（如相对路径）将相对于当前工作目录进行解析。有关完全更改工作目录的信息，请参阅 --directory。当在 uv pip 接口中使用时，此设置没有效果。
• --quiet, -q
  不打印任何输出
• --resolved
  写入解析后的 Python 解释器路径而不是请求。确保使用完全相同的解释器。此选项在将 .python-version 文件提交到版本控制时通常不安全。
• --verbose, -v
  使用详细输出。您可以使用 RUST_LOG 环境变量配置细粒度日志记录。（https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives）
• --version, -V
  显示 uv 版本

---

uv python dir

显示 uv Python 的安装目录。

默认情况下，Python 安装存储在 Unix 上的 $XDG_DATA_HOME/uv/python 或 $HOME/.local/share/uv/python，在 Windows 上为 %APPDATA%\uv\data\python。

Python 安装目录可以用 $UV_PYTHON_INSTALL_DIR 覆盖。

要查看 uv 安装 Python 可执行文件的目录，请使用 --bin 标志。注意，只有在启用预览模式时才会安装 Python 可执行文件。

---

使用方法

uv python dir [OPTIONS]

---

选项

• --allow-insecure-host allow-insecure-host
  允许对主机的不安全连接。可以多次提供。预期接收主机名（例如，localhost）、主机端口对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：列入此列表的主机将不会被与系统证书存储进行验证。仅在有验证来源的安全网络中使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您面临中间人攻击。也可以使用 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
  显示此命令的简要帮助信息
• --managed-python
  要求使用 uv-managed Python 版本。默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv-managed Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。也可以使用 UV_MANAGED_PYTHON 环境变量设置。
• --native-tls
  是否从平台的本地证书存储加载 TLS 证书。默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。webpki-roots 是来自 Mozilla 的可靠信任根集，将其包含在 uv 中可以提高可移植性和性能（尤其是在 macOS 上）。但是，在某些情况下，您可能希望使用平台的本地证书存储，尤其是如果您依赖包含在系统证书存储中的公司信任根（例如，强制代理），则更合适。也可以使用 UV_NATIVE_TLS 环境变量设置。
• --no-cache, -n
  避免从缓存中读取或写入，而是使用临时目录在整个操作期间使用。也可以使用 UV_NO_CACHE 环境变量设置。
• --no-config
  避免发现配置文件（pyproject.toml、uv.toml）。通常，配置文件会发现于当前目录、父目录或用户配置目录中。也可以使用 UV_NO_CONFIG 环境变量设置。
• --no-managed-python
  禁用 uv-managed Python 版本的使用。相反，uv 将在系统上搜索合适的 Python 版本。也可以使用 UV_NO_MANAGED_PYTHON 环境变量设置。
• --no-progress
  隐藏所有进度输出。例如，旋转器或进度条。也可以使用 UV_NO_PROGRESS 环境变量设置。
• --no-python-downloads
  禁用 Python 的自动下载。
• --offline
  禁用网络访问。当禁用时，uv 将仅使用本地缓存数据和本地可用的文件。也可以使用 UV_OFFLINE 环境变量设置。
• --project project
  在给定的项目目录中运行命令。所有 pyproject.toml、uv.toml 和 .python-version 文件将通过从项目根目录向上遍历目录树来发现，项目虚拟环境（.venv）也是如此。其他命令行参数（如相对路径）将以当前工作目录为相对路径解析。见 --directory 以完全更改工作目录。此设置在 uv pip 接口中使用时没有效果。
• --quiet, -q
  不打印任何输出
• --verbose, -v
  使用详细输出。您可以使用 RUST_LOG 环境变量配置细粒度日志记录。（https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives）
• --version, -V
  显示 uv 版本

---

uv python uninstall

卸载 Python 版本

---

使用方法

uv python uninstall [OPTIONS] <TARGETS>...

---

参数

• TARGETS
  要卸载的 Python 版本。查看支持的请求格式，请参阅 uv python。

---

选项

• --all
  卸载所有管理的 Python 版本
• --allow-insecure-host allow-insecure-host
  允许与主机的不安全连接。可以多次提供。预期接收主机名（例如，localhost）、主机-端口号对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：此列表中的主机将不会与系统证书存储进行验证。仅在安全的网络中且来源已验证的情况下使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您面临中间人攻击。还可以通过 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。此设置在 uv pip 接口中使用时没有效果。
• --help, -h
  显示此命令的简要帮助
• --install-dir, -i install-dir
  Python 被安装到的目录。还可以通过 UV_PYTHON_INSTALL_DIR 环境变量设置。
• --managed-python
  要求使用 uv-managed Python 版本。默认情况下，uv 倾向于使用它管理的 Python 版本。但是，如果没有安装 uv-managed Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。还可以通过 UV_MANAGED_PYTHON 环境变量设置。
• --native-tls
  是否从平台的本地证书存储加载 TLS 证书。默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。webpki-roots 是来自 Mozilla 的可靠信任根集，将它们包含在 uv 中可以提高可移植性和性能（尤其是在 macOS 上）。但是，在某些情况下，您可能希望使用平台的本地证书存储，尤其是如果您依赖于包含在系统证书存储中的企业信任根（例如，强制代理）时。还可以通过 UV_NATIVE_TLS 环境变量设置。
• --no-cache, -n
  避免从缓存中读取或写入，而是在整个操作期间使用临时目录。还可以通过 UV_NO_CACHE 环境变量设置。
• --no-config
  避免发现配置文件（pyproject.toml、uv.toml）。通常，配置文件将在当前目录、父目录或用户配置目录中找到。还可以通过 UV_NO_CONFIG 环境变量设置。
• --no-managed-python
  禁用 uv-managed Python 版本的使用。相反，uv 将在系统上搜索合适的 Python 版本。还可以通过 UV_NO_MANAGED_PYTHON 环境变量设置。
• --no-progress
  隐藏所有进度输出。例如，旋转器或进度条。还可以通过 UV_NO_PROGRESS 环境变量设置。
• --no-python-downloads
  禁用 Python 的自动下载。
• --offline
  禁用网络访问。当禁用时，uv 将仅使用本地缓存数据和本地可用的文件。还可以通过 UV_OFFLINE 环境变量设置。
• --project project
  在给定的项目目录中运行命令。所有 pyproject.toml、uv.toml 和 .python-version 文件将通过从项目根目录向上遍历目录树来发现，以及项目的虚拟环境（.venv）。其他命令行参数（例如相对路径）将与当前工作目录相关解析。有关更改整个工作目录的信息，请参阅 --directory。此设置在 uv pip 接口中使用时没有效果。
• --quiet, -q
  不打印任何输出
• --verbose, -v
  使用详细输出。您可以使用 RUST_LOG 环境变量配置细粒度日志记录。（https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives）
• --version, -V
  显示 uv 版本

---

uv pip

使用与 pip 兼容的接口管理 Python 包

---

使用方法

uv pip [OPTIONS] <COMMAND>

---

命令

• uv pip compile
  将 requirements.in 文件编译为 requirements.txt 文件
• uv pip sync
  同步环境与 requirements.txt 文件
• uv pip install
  将包安装到环境中
• uv pip uninstall
  从环境中卸载包
• uv pip freeze
  以要求格式列出环境中安装的包
• uv pip list
  以表格格式列出环境中安装的包
• uv pip show
  显示一个或多个已安装包的信息
• uv pip tree
  显示环境的依赖树
• uv pip check
  验证已安装的包是否有兼容的依赖

---

uv pip 编译

编译一个 requirements.in 文件到 requirements.txt 文件

---

使用方法

uv pip compile [OPTIONS] <SRC_FILE|--group <GROUP>>

---

参数

• SRC_FILE
  包含在给定的 requirements.in 文件中列出的所有包。如果提供了 pyproject.toml、setup.py 或 setup.cfg 文件，uv 将提取相关项目的需求。如果提供了 -，则需求将从标准输入中读取。需求文件及其中的需求的顺序用于在解析过程中确定优先级。

---

选项

• --all-extras
  包含所有可选依赖项。仅适用于 pyproject.toml、setup.py 和 setup.cfg 源。
• --allow-insecure-host allow-insecure-host
  允许对主机的不安全连接。可以多次提供。期望接收主机名（例如，localhost）、主机端口对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：列表中包含的主机将不会与系统的证书存储进行验证。仅在安全网络和验证源中使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您面临中间人攻击。也可以通过 UV_INSECURE_HOST 环境变量设置。
• --annotation-style annotation-style
  输出文件中包含的注释注释的样式，用于指示每个包的来源。默认为 split。可能的值：line：将注释渲染在单个逗号分隔的行上split：将每个注释渲染在其自己的行上
• --build-constraints, -b build-constraints
  在构建源分发时使用给定的需求文件来限制构建依赖项。约束文件类似于 requirements.txt 文件，但仅控制要安装的需求的 版本。然而，包括约束文件中的包将 不会 触发该包的安装。也可以通过 UV_BUILD_CONSTRAINT 环境变量设置。
• --cache-dir cache-dir
  缓存目录的路径。默认为 $XDG_CACHE_HOME/uv 或 macOS 和 Linux 上的 $HOME/.cache/uv，以及 Windows 上的 %LOCALAPPDATA%\uv\cache。要查看缓存目录的位置，请运行 uv cache dir。也可以通过 UV_CACHE_DIR 环境变量设置。
• --color color-choice
  控制输出中颜色的使用。默认情况下，uv 将在写入终端或 TTY 时自动检测对颜色的支持。可能的值：auto：仅在输出将写入支持颜色的终端或 TTY 时启用彩色输出always：无论检测到的环境如何，都启用彩色输出never：禁用彩色输出
• --config-file config-file
  要使用的 uv.toml 文件的路径。虽然 uv 配置可以包含在 pyproject.toml 文件中，但在此上下文中不允许。也可以通过 UV_CONFIG_FILE 环境变量设置。
• --config-setting, -C config-setting
  要传递给 PEP 517 构建后端的设置，指定为 KEY=VALUE 对
• --constraints, -c constraints
  使用给定的需求文件限制版本。约束文件类似于 requirements.txt 文件，但仅控制要安装的需求的 版本。然而，包括约束文件中的包将 不会 触发该包的安装。这与 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.org/simple）。接受符合 PEP 503（简单仓库 API）的存储库，或布局在相同格式的本地目录。此标志提供的索引比通过 --index 标志指定的所有其他索引

---

uv pip sync

同步一个与 requirements.txt 文件的环境

---

使用方法

uv pip sync [OPTIONS] <SRC_FILE>...

---

参数

• SRC_FILE
  包含在给定的 requirements.txt 文件中列出的所有包。如果提供了 pyproject.toml、setup.py 或 setup.cfg 文件，uv 将从相关项目中提取需求。如果提供了 -，则需求将从标准输入读取。

---

选项

• --allow-empty-requirements
  允许同步空需求，这将清除环境中的所有包
• --allow-insecure-host allow-insecure-host
  允许到主机的非安全连接。可以多次提供。期望接收主机名（例如，localhost）、主机-端口对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：列表中包含的主机将不会与系统证书存储进行验证。仅在安全网络和已验证源中使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您面临中间人攻击。也可以通过 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, -b build-constraints
  在构建源分布时使用给定的需求文件来约束构建依赖项。约束文件类似于 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：禁用彩色输出
• --compile-bytecode
  在安装后编译 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, -C config-setting
  以 KEY=VALUE 对的形式传递给 PEP 517 构建后端的设置
• --constraints, -c constraints
  使用给定的需求文件约束版本。约束文件类似于 requirements.txt 文件，但仅控制要安装的需求的 版本。然而，将包包含在约束文件中将 不会 触发该包的安装。这与 pip 的 --constraint 选项等效。也可以通过 UV_CONSTRAINT 环境变量设置。
• --default-index default-index
  默认包索引的 URL（默认：https://pypi.org/simple）。接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式排列的本地目录。此标志提供的索引优先级低于通过 --index 标志指定的所有其他索引。也可以通过 UV_DEFAULT_INDEX 环境变量设置。
• --directory directory
  在运行命令之前切换到给定的目录。相对路径将使用给定的目录作为基础。有关 --project 的信息，请参阅仅更改项目根目录。
• --dry-run
  执行 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 pip install

安装包到环境中

---

使用方法

uv pip install [OPTIONS] <PACKAGE|--requirements <REQUIREMENTS>|--editable <EDITABLE>|--group <GROUP>>

---

参数

• PACKAGE
  安装所有列出的包。包的顺序用于在解析期间确定优先级。

---

选项

• --all-extras
  包含所有可选依赖项。仅适用于 pyproject.toml、setup.py 和 setup.cfg 源。
• --allow-insecure-host allow-insecure-host
  允许对主机的不安全连接。可以多次提供。期望接收主机名（例如，localhost）、主机-端口号对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：列在此列表中的主机将不会与系统证书存储进行验证。仅在安全网络和已验证源中使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您面临中间人攻击。也可以通过 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, -b build-constraints
  在构建源分发时使用给定的需求文件来约束构建依赖项。约束文件类似于 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：禁用彩色输出
• --compile-bytecode
  在安装后编译 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, -C config-setting
  作为 KEY=VALUE 对传递给 PEP 517 构建后端的设置
• --constraints, -c constraints
  使用给定的需求文件约束版本。约束文件类似于 requirements.txt 文件，但仅控制要安装的需求的 版本。然而，在约束文件中包含包将 不会 触发该包的安装

---

uv pip uninstall

从环境中卸载包

---

使用方法

uv pip uninstall [OPTIONS] <PACKAGE|--requirements <REQUIREMENTS>>

---

参数

• PACKAGE
  卸载所有列出的包

---

选项

• --allow-insecure-host allow-insecure-host
  允许与主机的不安全连接。可以多次提供。预期接收主机名（例如，localhost）、主机端口对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：此列表中的主机将不会与系统的证书存储进行验证。仅在安全的网络和已验证的源中使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您容易受到中间人攻击。也可以通过 UV_INSECURE_HOST 环境变量设置。
• --break-system-packages
  允许 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 对远程需求文件进行身份验证。目前，仅支持 --keyring-provider subprocess，它配置 uv 使用 keyring CLI 来处理身份验证。默认为 disabled。也可以通过 UV_KEYRING_PROVIDER 环境变量设置。可能的值：disabled：不要使用 keyring 进行凭据查找；subprocess：使用 keyring 命令进行凭据查找
• --managed-python
  要求使用 uv-managed Python 版本。默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv-managed Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。也可以通过 UV_MANAGED_PYTHON 环境变量设置。
• --native-tls
  是否从平台的本地证书存储加载 TLS 证书。默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。webpki-roots 是来自 Mozilla 的可靠信任根集合，将其包含在 uv 中可以提高可移植性和性能（尤其是在 macOS 上）。但是，在某些情况下，您可能想使用平台的本地证书存储，尤其是如果您依赖于包含在系统证书存储中的企业信任根（例如，对于强制代理）。也可以通过 UV_NATIVE_TLS 环境变量设置。
• --no-break-system-packages
• --no-cache, -n
  避免从缓存中读取或写入，而是在操作期间使用临时目录。也可以通过 UV_NO_CACHE 环境变量设置。
• --no-config
  避免发现配置文件（pyproject.toml、uv.toml）。通常，配置文件将在当前目录、父目录或用户配置目录中查找。也可以通过 UV_NO_CONFIG 环境变量设置。
• --no-managed-python
  禁用 uv-managed Python 版本的使用。相反，uv 将在系统上搜索合适的 Python 版本。也可以通过 UV_NO_MANAGED_PYTHON 环境变量设置。
• --no-progress
  隐藏所有进度输出。例如，旋转器或进度条。也可以通过 UV_NO_PROGRESS 环境变量设置。
• --no-python-downloads
  禁止自动下载 Python。
• --offline
  禁用网络访问。当禁用时，uv 将仅使用本地缓存数据和本地可用文件。也可以通过 UV_OFFLINE 环境变量设置。
• --prefix prefix
  从指定的 --prefix 目录卸载包
• --project project
  在给定的项目目录中运行命令。所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历来发现，项目虚拟环境（.venv）也将被发现。其他命令行参数（如相对路径）将与当前工作目录相对解析。有关完全更改工作目录的信息，请参阅 --directory。在此设置用于 uv pip 接口时，此设置没有效果。
• --python, -p python
  应从其中卸载包的 Python 解释器。默认情况下，卸载需要虚拟环境。可以提供替代 Python 的路径，但仅在持续集成（CI）环境中推荐使用，并且应谨慎使用，因为它可以修改系统 Python 安装。有关 Python 发现和支持的请求格式的详细信息，请参阅 uv python。也可以通过 UV_PYTHON 环境变量设置。
• --quiet, -q
  不打印任何输出
• --requirements, -r requirements
  从给定需求文件中卸载所有包
• --system
  使用系统 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）
• --version, -V
  显示 uv 版本

---

uv pip freeze

以要求格式列出的，在环境中安装的包

---

使用方法

uv pip freeze [OPTIONS]

---

选项

• --allow-insecure-host allow-insecure-host
  允许对主机进行不安全连接。可以多次提供。期望接收主机名（例如，localhost）、主机-端口号对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：此列表中的主机将不会与系统证书存储进行验证。仅在安全网络和已验证的源中使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您面临中间人攻击。也可以通过 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
  显示此命令的简洁帮助
• --managed-python
  要求使用 uv-managed Python 版本。默认情况下，uv 倾向于使用它管理的 Python 版本。但是，如果没有安装 uv-managed Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。也可以通过 UV_MANAGED_PYTHON 环境变量设置。
• --native-tls
  是否从平台的本地证书存储加载 TLS 证书。默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。webpki-roots 是来自 Mozilla 的可靠信任根集，将其包含在 uv 中可以提高可移植性和性能（尤其是在 macOS 上）。但是，在某些情况下，您可能希望使用平台的本地证书存储，特别是如果您依赖于包含在系统证书存储中的企业信任根（例如，对于强制代理），可以设置 UV_NATIVE_TLS 环境变量。
• --no-cache, -n
  避免从缓存中读取或写入，而是在操作期间使用临时目录。也可以通过 UV_NO_CACHE 环境变量设置。
• --no-config
  避免发现配置文件（pyproject.toml、uv.toml）。通常，配置文件会在当前目录、父目录或用户配置目录中找到。也可以通过 UV_NO_CONFIG 环境变量设置。
• --no-managed-python
  禁用 uv-managed Python 版本的使用。相反，uv 将在系统上搜索合适的 Python 版本。也可以通过 UV_NO_MANAGED_PYTHON 环境变量设置。
• --no-progress
  隐藏所有进度输出。例如，旋转器或进度条。也可以通过 UV_NO_PROGRESS 环境变量设置。
• --no-python-downloads
  禁用 Python 的自动下载。
• --offline
  禁用网络访问。当禁用时，uv 将仅使用本地缓存的数据和本地可用的文件。也可以通过 UV_OFFLINE 环境变量设置。
• --path paths
  限制用于列出包的指定安装路径（可以多次使用）
• --project project
  在给定的项目目录中运行命令。所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历来发现，以及项目的虚拟环境（.venv）。其他命令行参数（例如相对路径）将相对于当前工作目录解析。参见 --directory 以完全更改工作目录。此设置在 uv pip 界面中使用时没有效果。
• --python, -p python
  应列出包的 Python 解释器。默认情况下，uv 在虚拟环境中列出包，但如果找不到虚拟环境，则将显示系统 Python 环境中的包。有关 Python 发现和受支持的请求格式的详细信息，请参阅 uv python。也可以通过 UV_PYTHON 环境变量设置。
• --quiet, -q
  不打印任何输出
• --strict
  验证 Python 环境，以检测缺少依赖项的包和其他问题
• --system
  在系统 Python 环境中列出包。禁用虚拟环境的发现。有关 Python 发现的详细信息，请参阅 uv python。也可以通过 UV_SYSTEM_PYTHON 环境变量设置。
• --verbose, -v
  使用详细输出。您可以使用 RUST_LOG 环境变量配置细粒度日志记录。（https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives）
• --version, -V
  显示 uv 版本

---

uv pip 列表

以表格格式列出在环境中安装的包

---

使用方法

uv pip list [OPTIONS]

---

选项

• --allow-insecure-host allow-insecure-host
  允许与主机的不安全连接。可以多次提供。预期接收主机名（例如，localhost）、主机-端口对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：此列表中的主机将不会与系统的证书存储进行验证。仅在安全网络和验证源中使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您面临中间人攻击。也可以通过 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 将在写入终端或 TTY 时自动检测对颜色的支持。可能的值：auto：仅在输出将发送到具有颜色支持的终端或 TTY 时启用彩色输出always：无论检测到的环境如何，都启用彩色输出never：禁用彩色输出
• --config-file config-file
  要使用的 uv.toml 文件的路径。虽然 uv 配置可以包含在 pyproject.toml 文件中，但在此上下文中不允许。也可以通过 UV_CONFIG_FILE 环境变量设置。
• --default-index default-index
  默认包索引的 URL（默认：https://pypi.org/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 标志时，较早的值具有优先权。也可以通过 UV_INDEX 环境变量设置。
• --index-strategy index-strategy
  解析多个索引 URL 时使用的策略。默认情况下，uv 将在给定包可用的第一个索引处停止，并将解析限制在第一个索引上存在的那些上（first-index）。这可以防止“依赖混淆”攻击，攻击者可以在替代索引上上传与同一名称相同的恶意包。也可以通过 UV_INDEX_STRATEGY 环境变量设置。可能的值：first-index：仅使用对给定包名称返回匹配的第一个索引的结果unsafe-first-match：在所有索引中搜索每个包名称，在移动到下一个索引之前耗尽第一个索引的版本unsafe-best-match：在所有索引中搜索每个包名称，优先考虑找到的“最佳”版本。如果包版本在多个索引中，则仅查看第一个索引的条目
• --index-url, -i index-url
  （已弃用：使用 --default-index 代替）Python 包索引的 URL（默认：https://pypi.org/simple）。接受符合 PEP 503（简单存储库 API）的存储库，或布局在相同格式的本地目录。此标志提供的索引优先级低于通过 --extra-index-url 标志指定的所有其他索引。也可以通过 UV_INDEX_URL 环境变量设置。
• --keyring-provider keyring-provider
  尝试使用 keyring 进行索引 URL 的身份验证。目前，仅支持 --keyring-provider subprocess，它配置 uv 使用 keyring CLI 来处理身份验证。默认为 disabled。也可以通过 UV_KEYRING_PROVIDER 环境变量设置。可能的值：disabled：不使用 keyring 进行凭据查找subprocess：使用 keyring 命令进行凭据查找
• --managed-python
  要求使用 uv-managed Python 版本。默认情况下，uv 倾向于使用它管理的 Python 版本。但是，如果没有安装 uv-managed Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。也可以通过 UV_MANAGED_PYTHON 环境变量设置。
• --native-tls
  是否从平台的本机证书存储加载 TLS 证书。默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。webpki-roots 是来自 Mozilla 的可靠的一组信任根，包括它们在 uv 中可以提高可移植性和性能（尤其是在 macOS 上）。但是，在某些情况下，您可能希望使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，强制代理），则更是如此。也可以通过 UV_NATIVE_TLS 环境变量设置。
• --no-cache, -n
  避免从缓存中读取或写入，而是在操作期间使用临时目录。也可以通过 UV_NO_CACHE 环境变量设置。
• --no-config
  避免发现配置文件（pyproject.toml、uv.toml）。通常，配置文件将在当前目录、父目录或用户配置目录中发现。也可以通过 UV_NO_CONFIG 环境变量设置。
• --no-index
  忽略注册表索引（例如，PyPI），而是依赖直接 URL 依赖项和通过 --find-links 提供的依赖项。
• --no-managed-python
  禁用 uv-managed Python 版本的使用。相反，uv 将在系统上搜索合适的 Python 版本。也可以通过 UV_NO_MANAGED_PYTHON 环境变量设置。
• --no-progress
  隐藏所有进度输出。例如，旋转器或进度条。也可以通过 UV_NO_PROGRESS 环境变量设置。
• --no-python-downloads
  禁用 Python 的自动下载。
• --offline
  禁用网络访问。当禁用时，uv 将仅使用本地缓存数据和本地可用文件。也可以通过 UV_OFFLINE 环境变量设置。
• --outdated
  列出过时的包。每个包的最新版本将显示与已安装版本并列。最新的包将从输出中省略。
• --project project
  在给定的项目目录中运行命令。所有 pyproject.toml、uv.toml 和 .python-version 文件将通过从项目根目录向上遍历目录树来发现，项目虚拟环境（.venv）也是如此。其他命令行参数（例如相对路径）将相对于当前工作目录进行解析。有关仅更改工作目录的信息，请参阅 --directory。在此设置用于 uv pip 接口时，此设置没有效果。
• --python, -p python
  应列出包的 Python 解释器。默认情况下，uv 在虚拟环境中列出包，但如果找不到虚拟环境，它将显示系统 Python 环境中的包。有关 Python 发现和受支持的请求格式的详细信息，请参阅 uv python。也可以通过 UV_PYTHON 环境变量设置。
• --quiet, -q
  不打印任何输出
• --strict
  验证 Python 环境，以检测缺失依赖项和其他问题
• --system
  列出系统 Python 环境中的包。禁用虚拟环境的发现。有关 Python 发现的详细信息，请参阅 uv python。也可以通过 UV_SYSTEM_PYTHON 环境变量设置。
• --verbose, -v
  使用详细输出。您可以使用 RUST_LOG 环境变量配置细粒度日志记录。（https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives）
• --version, -V
  显示 uv 版本

---

uv pip show

显示一个或多个已安装软件包的信息

---

使用方法

uv pip show [OPTIONS] [PACKAGE]...

---

参数

• PACKAGE
  要显示的包（们）

---

选项

• --allow-insecure-host allow-insecure-host
  允许与主机的不安全连接。可以多次提供。预期接收主机名（例如，localhost）、主机-端口号对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：此列表中的主机将不会与系统证书存储进行验证。仅在安全网络且来源已验证的情况下使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您面临中间人攻击。也可以通过 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
  显示此命令的简洁帮助
• --managed-python
  要求使用 uv-managed Python 版本。默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv-managed Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。也可以通过 UV_MANAGED_PYTHON 环境变量设置。
• --native-tls
  是否从平台的本地证书存储加载 TLS 证书。默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。webpki-roots 是来自 Mozilla 的可靠信任根集合，将其包含在 uv 中可以提高可移植性和性能（尤其是在 macOS 上）。但是，在某些情况下，您可能希望使用平台的本地证书存储，特别是如果您依赖于包含在系统证书存储中的企业信任根（例如，强制代理），则可能更适用。也可以通过 UV_NATIVE_TLS 环境变量设置。
• --no-cache, -n
  避免从缓存中读取或写入，而是在操作期间使用临时目录。也可以通过 UV_NO_CACHE 环境变量设置。
• --no-config
  避免发现配置文件（pyproject.toml、uv.toml）。通常，配置文件会在当前目录、父目录或用户配置目录中找到。也可以通过 UV_NO_CONFIG 环境变量设置。
• --no-managed-python
  禁用 uv-managed Python 版本的使用。相反，uv 将在系统上搜索合适的 Python 版本。也可以通过 UV_NO_MANAGED_PYTHON 环境变量设置。
• --no-progress
  隐藏所有进度输出。例如，旋转器或进度条。也可以通过 UV_NO_PROGRESS 环境变量设置。
• --no-python-downloads
  禁用 Python 的自动下载。
• --offline
  禁用网络访问。当禁用时，uv 将仅使用本地缓存的数据和本地可用的文件。也可以通过 UV_OFFLINE 环境变量设置。
• --project project
  在给定的项目目录中运行命令。所有 pyproject.toml、uv.toml 和 .python-version 文件将通过从项目根目录向上遍历目录树来发现，以及项目的虚拟环境（.venv）。其他命令行参数（如相对路径）将相对于当前工作目录解析。有关 --directory 的信息，请参阅完全更改工作目录。当在 uv pip 接口中使用时，此设置没有效果。
• --python, -p python
  查找包的 Python 解释器。默认情况下，uv 在虚拟环境中查找包，但如果找不到虚拟环境，它将查找系统 Python 环境中的包。有关 Python 发现的详细信息，请参阅 uv python。也可以通过 UV_PYTHON 环境变量设置。
• --quiet, -q
  不打印任何输出
• --strict
  验证 Python 环境，以检测缺失依赖项和其他问题
• --system
  在系统 Python 环境中显示包。禁用虚拟环境的发现。有关 Python 发现的详细信息，请参阅 uv python。也可以通过 UV_SYSTEM_PYTHON 环境变量设置。
• --verbose, -v
  使用详细输出。您可以使用 RUST_LOG 环境变量配置细粒度日志记录。（https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives）
• --version, -V
  显示 uv 版本

---

uv pip tree

显示环境依赖树

---

使用方法

uv pip tree [OPTIONS]

---

选项

• --allow-insecure-host allow-insecure-host
  允许到主机的非安全连接。可以多次提供。预期接收主机名（例如，localhost）、主机端口对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：列入此列表的主机将不会与系统的证书存储进行验证。仅在安全网络中且来源已验证的情况下使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您面临中间人攻击。也可以通过 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.org/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）的存储库，或按相同格式排列的本地目录。通过此标志提供的所有索引的优先级高于 --extra-index-url 标志指定的索引（默认为 PyPI）。当提供多个 --extra-index-url 标志时，早期值具有优先权。也可以通过 UV_EXTRA_INDEX_URL 环境变量设置。
• --find-links, -f find-links
  在注册表索引中找到的候选分发的位置，包括其他位置。如果是一个路径，目标必须是一个包含包（.whl 或源分发，例如 .tar.gz 或 .zip）的目录。如果是一个 URL，页面必须包含一个符合上述格式的包文件的平铺链接列表。也可以通过 UV_FIND_LINKS 环境变量设置。
• --help, -h
  显示此命令的简洁帮助
• --index index
  解析依赖关系时使用的 URL，除了默认索引。接受符合 PEP 503（简单存储库 API）的存储库，或按相同格式排列的本地目录。通过此标志提供的所有索引的优先级高于 --default-index 标志指定的索引（默认为 PyPI）。当提供多个 --index 标志时，早期值具有优先权。也可以通过 UV_INDEX 环境变量设置。
• --index-strategy index-strategy
  解析多个索引 URL 时使用的策略。默认情况下，uv 将在找到给定包名称的第一个索引处停止，并将解析限制在该第一个索引上（first-index）。这可以防止“依赖混淆”攻击，攻击者可以在备用索引上以相同名称上传恶意包。也可以通过 UV_INDEX_STRATEGY 环境变量设置。可能的值：first-index：仅使用对给定包名称返回匹配的第一个索引的结果；unsafe-first-match：搜索所有索引中的每个包名称，在移到下一个索引之前先耗尽第一个索引的版本；unsafe-best-match：搜索所有索引中的每个包名称，优先考虑找到的“最佳”版本。如果包版本在多个索引中，则只查看第一个索引的条目
• --index-url, -i index-url
  （已弃用：请使用 --default-index 代替）Python 包索引的 URL（默认：https://pypi.org/simple）。接受符合 PEP 503（简单存储库 API）的存储库，或按相同格式排列的本地目录。此标志提供的索引的优先级低于通过 --extra-index-url 标志指定的所有其他索引。也可以通过 UV_INDEX_URL 环境变量设置。
• --invert
  显示给定包的逆向依赖关系。此标志将反转树并显示依赖于给定包的包
• --keyring-provider keyring-provider
  尝试使用 keyring 进行索引 URL 的身份验证。目前，仅支持 --keyring-provider subprocess，它配置 uv 使用 keyring CLI 来处理身份验证。默认为 disabled。也可以通过 UV_KEYRING_PROVIDER 环境变量设置。可能的值：disabled：不要使用 keyring 进行凭据查找；subprocess：使用 keyring 命令进行凭据查找
• --managed-python
  要求使用 uv-managed Python 版本。默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv-managed Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。也可以通过 UV_MANAGED_PYTHON 环境变量设置。
• --native-tls
  是否从平台的本地证书存储加载 TLS 证书。默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。webpki-roots 是来自 Mozilla 的可靠信任根集合，包括它们在 uv 中可以提高可移植性和性能（尤其是在 macOS 上）。但是，在某些情况下，您可能希望使用平台的本地证书存储，特别是如果您依赖于包含在系统证书存储中的企业信任根（例如，对于强制代理），则可能需要这样做。也可以通过 UV_NATIVE_TLS 环境变量设置。
• --no-cache, -n
  避免从缓存中读取或写入，而是在整个操作期间使用临时目录。也可以通过 UV_NO_CACHE 环境变量设置。
• --no-config
  避免发现配置文件（pyproject.toml、uv.toml）。通常，配置文件将在当前目录、父目录或用户配置目录中发现。也可以通过 UV_NO_CONFIG 环境变量设置。
• --no-dedupe
  不去重重复依赖项。通常，当包已显示其依赖项时，进一步的 occurrence 将不会重新显示其依赖项，并且将包括一个 (*) 来指示它已显示。此标志将导致这些重复项重复
• --no-index
  忽略注册表索引（例如，PyPI），而是依赖于直接 URL 依赖项和通过 --find-links 提供的依赖项
• --no-managed-python
  禁用 uv-managed Python 版本的使用。相反，uv 将在系统上搜索合适的 Python 版本。也可以通过 UV_NO_MANAGED_PYTHON 环境变量设置。
• --no-progress
  隐藏所有进度输出。例如，旋转器或进度条。也可以通过 UV_NO_PROGRESS 环境变量设置。
• --no-python-downloads
  禁用 Python 的自动下载。
• --offline
  禁用网络访问。禁用时，uv 将仅使用本地缓存数据和本地可用文件。也可以通过 UV_OFFLINE 环境变量设置。
• --outdated
  显示树中每个包的最新可用版本
• --package package
  仅显示指定的包
• --project project
  在给定的项目目录中运行命令。所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历目录树来发现，以及项目的虚拟环境（.venv）。其他命令行参数（例如相对路径）将相对于当前工作目录进行解析。请参阅 --directory 以更改整个工作目录。此设置在 uv pip 接口中使用时没有效果。
• --prune prune
  从依赖树显示中删除给定的包
• --python, -p python
  应列出包的 Python 解释器。默认情况下，uv 在虚拟环境中列出包，但如果找不到虚拟环境，则将显示系统 Python 环境中的包。请参阅 uv python 了解 Python 发现和受支持的请求格式。也可以通过 UV_PYTHON 环境变量设置。
• --quiet, -q
  不打印任何输出
• --show-version-specifiers
  显示对每个包施加的版本约束
• --strict
  验证 Python 环境，以检测缺少依赖项和其他问题的包
• --system
  列出系统 Python 环境中的包。禁用虚拟环境的发现。请参阅 uv python 了解 Python 发现的详细信息。也可以通过 UV_SYSTEM_PYTHON 环境变量设置。
• --verbose, -v
  使用详细输出。您可以使用 RUST_LOG 环境变量配置细粒度日志记录。（https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives）
• --version, -V
  显示 uv 版本

---

uv pip check

验证已安装的软件包是否具有兼容的依赖关系

---

使用方法

uv pip check [OPTIONS]

---

选项

• --allow-insecure-host allow-insecure-host
  允许与主机的不安全连接。可以多次提供。期望接收主机名（例如，localhost）、主机-端口对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：列表中包含的主机将不会与系统的证书存储进行验证。仅在安全网络和已验证的源中使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您面临中间人攻击。也可以通过 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
  显示此命令的简洁帮助信息
• --managed-python
  要求使用 uv-managed Python 版本。默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv-managed Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。也可以通过 UV_MANAGED_PYTHON 环境变量设置。
• --native-tls
  是否从平台的本地证书存储中加载 TLS 证书。默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。webpki-roots 是来自 Mozilla 的可靠信任根集合，将其包含在 uv 中可以提高可移植性和性能（尤其是在 macOS 上）。但是，在某些情况下，您可能希望使用平台的本地证书存储，尤其是如果您依赖于包含在系统证书存储中的企业信任根（例如，强制代理）。也可以通过 UV_NATIVE_TLS 环境变量设置。
• --no-cache, -n
  避免从缓存中读取或写入，而是在操作期间使用临时目录。也可以通过 UV_NO_CACHE 环境变量设置。
• --no-config
  避免发现配置文件（pyproject.toml、uv.toml）。通常，配置文件会发现当前目录、父目录或用户配置目录中。也可以通过 UV_NO_CONFIG 环境变量设置。
• --no-managed-python
  禁用 uv-managed Python 版本的使用。相反，uv 将在系统上搜索合适的 Python 版本。也可以通过 UV_NO_MANAGED_PYTHON 环境变量设置。
• --no-progress
  隐藏所有进度输出。例如，旋转器或进度条。也可以通过 UV_NO_PROGRESS 环境变量设置。
• --no-python-downloads
  禁用 Python 的自动下载。
• --offline
  禁用网络访问。当禁用时，uv 将仅使用本地缓存数据和本地可用文件。也可以通过 UV_OFFLINE 环境变量设置。
• --project project
  在给定的项目目录中运行命令。所有 pyproject.toml、uv.toml 和 .python-version 文件将通过从项目根目录向上遍历目录树来发现，项目虚拟环境（.venv）也是如此。其他命令行参数（如相对路径）将与当前工作目录相关解析。参见 --directory 以完全更改工作目录。当在 uv pip 接口中使用时，此设置没有效果。
• --python, -p python
  应检查的 Python 解释器。默认情况下，uv 在虚拟环境中检查包，但如果未找到虚拟环境，它将检查系统 Python 环境中的包。有关 Python 发现的详细信息，请参阅 uv python。也可以通过 UV_PYTHON 环境变量设置。
• --quiet, -q
  不打印任何输出
• --system
  在系统 Python 环境中检查包。禁用虚拟环境的发现。有关 Python 发现的详细信息，请参阅 uv python。也可以通过 UV_SYSTEM_PYTHON 环境变量设置。
• --verbose, -v
  使用详细输出。您可以使用 RUST_LOG 环境变量配置细粒度日志记录。（https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives）
• --version, -V
  显示 uv 版本

---

uv venv

创建一个虚拟环境。

默认情况下，在当前工作目录中创建名为 .venv 的虚拟环境。也可以通过位置参数提供替代路径。

如果在项目中，可以通过 UV_PROJECT_ENVIRONMENT 环境变量更改默认环境名称；这仅适用于从项目根目录运行时。

如果在目标路径存在虚拟环境，它将被删除，并创建一个新的空虚拟环境。

当使用 uv 时，不需要激活虚拟环境。uv 将在工作目录或任何父目录中查找名为 .venv 的虚拟环境。

---

使用方法

uv venv [OPTIONS] [PATH]

---

参数

• PATH
  创建虚拟环境的路径。默认为工作目录中的 .venv。相对路径相对于工作目录解析。

---

选项

• --allow-existing
  保留目标路径上现有的任何文件或目录。默认情况下，uv venv 将删除给定路径上的现有虚拟环境，并在路径非空但 不是 虚拟环境时退出并显示错误。--allow-existing 选项将写入给定路径，无论其内容如何，而无需事先清除。警告：如果现有的虚拟环境和新建的虚拟环境链接到不同的 Python 解释器，此选项可能会导致意外的行为。
• --allow-insecure-host allow-insecure-host
  允许与主机的不安全连接。可以多次提供。期望接收主机名（例如，localhost）、主机-端口对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：此列表中包含的主机将不会与系统的证书存储进行验证。仅在安全网络和已验证的源中使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您面临中间人攻击。也可以通过 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.org/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
  在注册表索引中找到的候选分发的位置，包括那些通过 --find-links 提供的。如果是一个路径，目标必须是包含包作为 wheel 文件（.whl）或源分发（例如，.tar.gz 或 .zip）的目录。如果是一个 URL，页面必须包含符合上述格式的包文件的平坦列表。也可以通过 UV_FIND_LINKS 环境变量设置。
• --help, -h
  显示此命令的简洁帮助
• --index index
  解析依赖关系时使用的 URL，包括默认索引。接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。通过此标志提供的所有索引都优先于 --default-index 标志指定的索引（默认为 PyPI）。当提供多个 --index 标志时，较早的值具有优先级。也可以通过 UV_INDEX 环境变量设置。
• --index-strategy index-strategy
  解析多个索引 URL 时使用的策略。默认情况下，uv 将在给定包可用的第一个索引处停止，并将解析限制在第一个索引上存在的那些上（first-index）。这可以防止“依赖混淆”攻击，攻击者可以在替代索引中上传具有相同名称的恶意包。也可以通过 UV_INDEX_STRATEGY 环境变量设置。可能的值：first-index：仅使用针对给定包名称返回匹配的第一个索引的结果unsafe-first-match：在所有索引中搜索每个包名称，在移动到下一个索引之前耗尽第一个索引的版本unsafe-best-match：在所有索引中搜索每个包名称，优先选择找到的“最佳”版本。如果包版本在多个索引中，则仅查看第一个索引的条目
• --index-url, -i index-url
  （已弃用：使用 --default-index 代替）Python 包索引的 URL（默认：https://pypi.org/simple）。接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。此标志提供的索引比通过 --extra-index-url 标志指定的所有其他索引具有较低优先级。也可以通过 UV_INDEX_URL 环境变量设置。
• --keyring-provider keyring-provider
  尝试使用 keyring 进行索引 URL 的身份验证。目前，仅支持 --keyring-provider subprocess，它配置 uv 使用 keyring CLI 来处理身份验证。默认为 disabled。也可以通过 UV_KEYRING_PROVIDER 环境变量设置。可能的值：disabled：不使用 keyring 进行凭据查找subprocess：使用 keyring 命令进行凭据查找
• --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 目录的符号链接
• --managed-python
  要求使用 uv-managed Python 版本。默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv-managed Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。也可以通过 UV_MANAGED_PYTHON 环境变量设置。
• --native-tls
  是否从平台的本地证书存储加载 TLS 证书。默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。webpki-roots 是来自 Mozilla 的可靠的一组信任根，将其包含在 uv 中可以提高可移植性和性能（尤其是在 macOS 上）。但是，在某些情况下，您可能想使用平台的本地证书存储，特别是如果您依赖于包含在系统证书存储中的企业信任根（例如，强制代理），则可能更想使用它。也可以通过 UV_NATIVE_TLS 环境变量设置。
• --no-cache, -n
  避免从缓存中读取或写入，而是在整个操作期间使用临时目录。也可以通过 UV_NO_CACHE 环境变量设置。
• --no-config
  避免发现配置文件（pyproject.toml、uv.toml）。通常，配置文件会在当前目录、父目录或用户配置目录中找到。也可以通过 UV_NO_CONFIG 环境变量设置。
• --no-index
  忽略注册表索引（例如，PyPI），而是依赖直接 URL 依赖项和通过 --find-links 提供的依赖项。
• --no-managed-python
  禁用 uv-managed Python 版本的使用。相反，uv 将在系统上搜索合适的 Python 版本。也可以通过 UV_NO_MANAGED_PYTHON 环境变量设置。
• --no-progress
  隐藏所有进度输出。例如，旋转器或进度条。也可以通过 UV_NO_PROGRESS 环境变量设置。
• --no-project
  避免发现项目或工作区。默认情况下，uv 在当前目录或任何父目录中搜索项目，以确定虚拟环境的默认路径并检查是否存在 Python 版本约束。也可以通过 UV_NO_PROJECT 环境变量设置。
• --no-python-downloads
  禁用 Python 的自动下载。
• --offline
  禁用网络访问。当禁用时，uv 将仅使用本地缓存数据和本地可用的文件。也可以通过 UV_OFFLINE 环境变量设置。
• --project project
  在给定的项目目录中运行命令。所有 pyproject.toml、uv.toml 和 .python-version 文件将通过从项目根目录向上遍历来发现，项目的工作环境（.venv）也是如此。其他命令行参数（如相对路径）将相对于当前工作目录进行解析。有关 --directory 的信息，请参阅完全更改工作目录。在此设置中，当在 uv pip 接口中使用时，此设置没有效果。
• --prompt prompt
  为虚拟环境提供替代提示前缀。默认情况下，提示取决于是否向 uv venv 提供了路径。如果提供了（例如，uv venv project），则提示设置为目录名。如果没有提供（例如，uv venv），则提示设置为当前目录的名称。如果提供了 “.”，则无论是否向 uv venv 提供了路径，都将使用当前目录的名称。
• --python, -p python
  用于虚拟环境的 Python 解释器。在创建虚拟环境期间，uv 不会在虚拟环境中查找 Python 解释器。有关 Python 发现和受支持的请求格式的详细信息，请参阅 uv python。也可以通过 UV_PYTHON 环境变量设置。
• --quiet, -q
  不打印任何输出
• --refresh
  刷新所有缓存数据
• --refresh-package refresh-package
  刷新特定包的缓存数据
• --relocatable
  使虚拟环境可移动。可移动的虚拟环境可以在移动和重新分发时保持其关联的入口点和激活脚本的有效性。请注意，这仅适用于标准的 console_scripts 和 gui_scripts。其他脚本可能会根据它们是否带有通用的 #!python[w] shebang 进行调整，而二进制文件保持不变。由于使环境可移动（通过写入相对路径而不是绝对路径），入口点和脚本本身将 不会 可移动。换句话说，将这些入口点和脚本复制到环境之外的位置将不起作用，因为它们引用环境本身的相对路径。
• --seed
  将种子包（一个或多个：pip、setuptools 和 wheel）安装到虚拟环境中。请注意，setuptools 和 wheel 不包含在 Python 3.12+ 环境中。也可以通过 UV_VENV_SEED 环境变量设置。
• --system-site-packages
  使虚拟环境能够访问系统站点包目录。与 pip 不同，当使用 --system-site-packages 创建虚拟环境时，uv 将 不会 在运行 uv pip list 或 uv pip install 等命令时考虑系统站点包。--system-site-packages 标志将在运行时为虚拟环境提供对系统站点包目录的访问权限，但不会影响 uv 命令的行为。
• --verbose, -v
  使用详细输出。您可以使用 RUST_LOG 环境变量配置细粒度日志记录。（https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives）
• --version, -V
  显示 uv 版本

---

uv 构建

将 Python 包构建成源代码分发和 wheels。

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 中的源发行版存档。默认为当前工作目录。

---

选项

• --all-packages
  构建工作区中的所有包。工作区将来自提供的源目录，如果没有提供源目录，则来自当前目录。如果工作区成员不存在，uv 将出错退出。
• --allow-insecure-host allow-insecure-host
  允许与主机建立不安全连接。可以多次提供。预期接收主机名（例如，localhost）、主机-端口对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：列表中包含的主机将不会与系统证书存储进行验证。仅在安全网络且来源已验证的情况下使用 --allow-insecure-host，因为它绕过 SSL 验证，可能会使您容易受到中间人攻击。也可以通过 UV_INSECURE_HOST 环境变量设置。
• --build-constraints, -b build-constraints
  在构建发行版时，使用给定的要求文件约束构建依赖项。约束文件类似于 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, -C config-setting
  作为 KEY=VALUE 对传递给 PEP 517 构建后端的设置
• --default-index default-index
  默认包索引的 URL（默认：https://pypi.org/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 标志时，较早的值具有更高的优先级。也可以通过 UV_INDEX 环境变量设置。
• --index-strategy index-strategy
  在多个索引 URL 上解析时要使用的策略。默认情况下，uv 将在给定包可用的第一个索引处停止，并将解析限制在第一个索引上存在的那些上（first-index）。这可以防止“依赖项混淆”攻击，攻击者可以将恶意包上传到替代索引下，具有相同的名称。也可以通过 UV_INDEX_STRATEGY 环境变量设置。可能的值：first-index：仅使用第一个索引返回给定包名称的匹配结果的结果unsafe-first-match：在所有索引中搜索每个包名称，在移动到下一个索引之前耗尽第一个索引的版本unsafe-best-match：在所有索引中搜索每个包名称，优先考虑找到的“最佳”版本。如果包版本在多个索引中，则仅查看第一个索引的条目
• --index-url, -i index-url
  （已弃用：请使用 --default-index）Python 包索引的 URL（默认：https://pypi.org/simple）。接受符合 PEP 503 的存储库（简单存储库 API），或以相同格式布局的本地目录。此标志给出的索引比通过 --extra-index-url 标志指定的所有其他索引具有较低的优先级。也可以通过 UV_INDEX_URL 环境变量设置。
• --keyring-provider keyring-provider
  尝试使用 keyring 进行索引 URL 的身份验证。目前，仅支持 --keyring-provider subprocess，它配置 uv 使用 keyring CLI 来处理身份验证。默认为 disabled。也可以通过 UV_KEYRING_PROVIDER 环境变量设置。可能的值：disabled：不使用 keyring 进行凭据查找subprocess：使用 keyring 命令进行凭据查找
• --link-mode link-mode
  当从全局缓存安装包时要使用的方法。此选项仅在构建源发行版时使用。默认情况下，在 macOS 上为 clone（也称为 Copy-on-Write），在 Linux 和 Windows 上为 hardlink。也可以通过 UV_LINK_MODE 环境变量设置。可能的值：clone：从 wheel 中克隆（即复制-on-write）包到 site-packages 目录copy：从 wheel 中复制包到 site-packages 目录hardlink：从 wheel 中创建硬链接到 site-packages 目录symlink：从 wheel 中创建符号链接到 site-packages 目录
• --managed-python
  要求使用 uv-managed Python 版本。默认情况下，uv 优先使用它管理的 Python 版本。如果没有安装 uv-managed Python，则将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。也可以通过 UV_MANAGED_PYTHON 环境变量设置。
• --native-tls
  是否从平台的本地证书存储中加载 TLS 证书。默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。webpki-roots 是来自 Mozilla 的可靠的一组信任根，包括它们在 uv 中可以提高可移植性和性能（特别是在 macOS 上）。但是，在某些情况下，您可能想使用平台的本地证书存储，特别是如果您依赖于包含在系统证书存储中的公司信任根（例如，强制代理），则尤其如此。也可以通过 UV_NATIVE_TLS 环境变量设置。
• --no-binary
  不要安装预构建的 wheel。给定的包将从头开始构建和安装。解析器仍会使用可用的预构建 wheel 提取包元数据，如果有的话。也可以通过 UV_NO_BINARY 环境变量设置。
• --no-binary-package no-binary-package
  不要为特定包安装预构建的 wheel。也可以通过 UV_NO_BINARY_PACKAGE 环境变量设置。
• --no-build
  不要构建源发行版。启用时，解析将不会运行任意 Python 代码。将重用已构建源发行版的缓存 wheel，但需要构建发行版的操作将出错退出。也可以通过 UV_NO_BUILD 环境变量设置。
• --no-build-isolation
  禁用构建源发行版时的隔离。假设 PEP 518 中指定的构建依赖项已经安装。也可以通过 UV_NO_BUILD_ISOLATION 环境变量设置。
• --no-build-isolation-package no-build-isolation-package
  在构建特定包的源发行版时禁用隔离。假设该包的 PEP 518 中指定的构建依赖项已经安装。
• --no-build-logs
  隐藏构建后端日志
• --no-build-package no-build-package
  不要为特定包构建源发行版。也可以通过 UV_NO_BUILD_PACKAGE 环境变量设置。
• --no-cache, -n
  避免从缓存中读取或写入，而是在整个操作期间使用临时目录。也可以通过 UV_NO_CACHE 环境变量设置。
• --no-config
  避免发现配置文件（pyproject.toml、uv.toml）。通常，配置文件会在当前目录、父目录或用户配置目录中发现。也可以通过 UV_NO_CONFIG 环境变量设置。
• --no-index
  忽略注册索引（例如，PyPI），而是依赖于直接 URL 依赖项和通过 --find-links 提供的依赖项
• --no-managed-python
  禁用 uv-managed Python 版本的使用。相反，uv 将在系统上搜索合适的 Python 版本。也可以通过 UV_NO_MANAGED_PYTHON 环境变量设置。
• --no-progress
  隐藏所有进度输出。例如，旋转器或进度条。也可以通过 UV_NO_PROGRESS 环境变量设置。
• --no-python-downloads
  禁用 Python 的自动下载。
• --no-sources
  在解析依赖

---

uv publish

上传分发到索引

---

使用方法

uv publish [OPTIONS] [FILES]...

---

参数

• FILES
  要上传的文件路径。接受通配符表达式。默认为 dist 目录。仅选择 wheels 和源分发，而忽略其他文件。

---

选项

• --allow-insecure-host allow-insecure-host
  允许与主机的不安全连接。可以多次提供。期望接收主机名（例如，localhost）、主机-端口对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：列表中包含的主机将不会与系统的证书存储进行验证。仅在安全网络和已验证源中使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您面临中间人攻击。也可以通过 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。也可以通过 UV_CONFIG_FILE 环境变量设置。
• --help, -h
  显示此命令的简洁帮助
• --index index
  要用于发布的配置中索引的名称。索引必须有一个 publish-url 设置，例如：The index url will be used to check for existing files to skip duplicate uploads. With these settings, the following two calls are equivalent:也可以通过 UV_PUBLISH_INDEX 环境变量设置。
• --keyring-provider keyring-provider
  尝试使用 keyring 对远程需求文件进行身份验证。目前，仅支持 --keyring-provider subprocess，它配置 uv 使用 keyring CLI 来处理身份验证。默认为 disabled。也可以通过 UV_KEYRING_PROVIDER 环境变量设置。可能的值：disabled：不要使用 keyring 进行凭据查找subprocess：使用 keyring 命令进行凭据查找
• --managed-python
  要求使用 uv-managed Python 版本。默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv-managed Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。也可以通过 UV_MANAGED_PYTHON 环境变量设置。
• --native-tls
  是否从平台的本地证书存储加载 TLS 证书。默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。webpki-roots 是来自 Mozilla 的可靠信任根集合，将其包含在 uv 中可以提高可移植性和性能（尤其是在 macOS 上）。但是，在某些情况下，您可能希望使用平台的本地证书存储，特别是如果您依赖于包含在系统证书存储中的企业信任根（例如，强制代理），则更是如此。也可以通过 UV_NATIVE_TLS 环境变量设置。
• --no-cache, -n
  避免从缓存中读取或写入，而是在操作期间使用临时目录。也可以通过 UV_NO_CACHE 环境变量设置。
• --no-config
  避免发现配置文件（pyproject.toml、uv.toml）。通常，配置文件会在当前目录、父目录或用户配置目录中发现。也可以通过 UV_NO_CONFIG 环境变量设置。
• --no-managed-python
  禁用 uv-managed Python 版本的使用。相反，uv 将在系统上搜索合适的 Python 版本。也可以通过 UV_NO_MANAGED_PYTHON 环境变量设置。
• --no-progress
  隐藏所有进度输出。例如，旋转器或进度条。也可以通过 UV_NO_PROGRESS 环境变量设置。
• --no-python-downloads
  禁用 Python 的自动下载。
• --offline
  禁用网络访问。当禁用时，uv 将仅使用本地缓存的数据和本地可用的文件。也可以通过 UV_OFFLINE 环境变量设置。
• --password, -p password
  上传的密码。也可以通过 UV_PUBLISH_PASSWORD 环境变量设置。
• --project project
  在给定的项目目录中运行命令。所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历来发现，以及项目的虚拟环境（.venv）。其他命令行参数（如相对路径）将相对于当前工作目录解析。有关完全更改工作目录的信息，请参阅 --directory。此设置在 uv pip 接口中使用时没有效果。也可以通过 UV_CONFIG_FILE 环境变量设置。
• --publish-url publish-url
  上传端点的 URL（不是索引 URL）。请注意，通常索引访问（例如，https:://.../simple）和索引上传有不同的 URL。默认为 PyPI 的发布 URL（https://upload.pypi.org/legacy/）。也可以通过 UV_PUBLISH_URL 环境变量设置。
• --quiet, -q
  不打印任何输出
• --token, -t token
  上传的令牌。使用令牌与传递 __token__ 作为 --username 并将令牌作为 --password 密码等效。也可以通过 UV_PUBLISH_TOKEN 环境变量设置。
• --trusted-publishing trusted-publishing
  通过 GitHub Actions 配置使用受信任的发布。默认情况下，uv 在 GitHub Actions 中运行时会检查受信任的发布，但如果未配置或工作流程没有足够的权限（例如，来自分叉的拉取请求）则会忽略它。可能的值：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）
• --version, -V
  显示 uv 版本

---

uv 缓存

管理 uv 的缓存

---

使用方法

uv cache [OPTIONS] <COMMAND>

---

命令

• uv cache clean
  清除缓存，移除所有条目或与特定包关联的条目
• uv cache prune
  从缓存中删除所有不可达的对象
• uv cache dir
  显示缓存目录

---

uv 缓存清理

清除缓存，删除所有条目或与特定软件包相关的条目

---

使用方法

uv cache clean [OPTIONS] [PACKAGE]...

---

参数

• PACKAGE
  从缓存中移除的软件包

---

选项

• --allow-insecure-host allow-insecure-host
  允许到主机的非安全连接。可以多次提供。期望接收主机名（例如，localhost）、主机-端口号对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：包含在此列表中的主机将不会与系统证书存储进行验证。仅在安全网络和验证来源中使用 --allow-insecure-host，因为它绕过 SSL 验证，可能会使您容易受到中间人攻击。也可以通过 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
  显示此命令的简要帮助
• --managed-python
  要求使用 uv-managed Python 版本。默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv-managed Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。也可以通过 UV_MANAGED_PYTHON 环境变量设置。
• --native-tls
  是否从平台的本地证书存储加载 TLS 证书。默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。webpki-roots 是来自 Mozilla 的可靠信任根集合，将其包含在 uv 中可以提高可移植性和性能（尤其是在 macOS 上）。但是，在某些情况下，您可能希望使用平台的本地证书存储，尤其是如果您依赖于包含在系统证书存储中的企业信任根（例如，强制代理），则更是如此。也可以通过 UV_NATIVE_TLS 环境变量设置。
• --no-cache, -n
  避免从缓存中读取或写入，而是在操作期间使用临时目录。也可以通过 UV_NO_CACHE 环境变量设置。
• --no-config
  避免发现配置文件（pyproject.toml、uv.toml）。通常，配置文件会在当前目录、父目录或用户配置目录中发现。也可以通过 UV_NO_CONFIG 环境变量设置。
• --no-managed-python
  禁用 uv-managed Python 版本的使用。相反，uv 将在系统上搜索合适的 Python 版本。也可以通过 UV_NO_MANAGED_PYTHON 环境变量设置。
• --no-progress
  隐藏所有进度输出。例如，旋转器或进度条。也可以通过 UV_NO_PROGRESS 环境变量设置。
• --no-python-downloads
  禁用 Python 的自动下载。
• --offline
  禁用网络访问。当禁用时，uv 只会使用本地缓存数据和本地可用文件。也可以通过 UV_OFFLINE 环境变量设置。
• --project project
  在给定的项目目录中运行命令。所有 pyproject.toml、uv.toml 和 .python-version 文件都将在从项目根目录向上遍历目录树时发现，项目虚拟环境（.venv）也是如此。其他命令行参数（如相对路径）将以当前工作目录为基准进行解析。有关完全更改工作目录的说明，请参阅 --directory。当在 uv pip 接口中使用时，此设置没有效果。
• --quiet, -q
  不打印任何输出
• --verbose, -v
  使用详细输出。您可以使用 RUST_LOG 环境变量配置细粒度日志记录。（https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives）
• --version, -V
  显示 uv 版本

---

uv cache prune

修剪缓存中所有不可达的对象

---

使用方法

uv cache prune [OPTIONS]

---

选项

• --allow-insecure-host allow-insecure-host
  允许与主机的不安全连接。可以多次提供。期望接收主机名（例如，localhost）、主机-端口号对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：此列表中包含的主机将不会与系统的证书存储进行验证。仅在安全网络且来源已验证的情况下使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您面临中间人攻击。也可以通过 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 会缓存从源构建的轮和直接下载的预构建轮，以实现高性能的包安装。然而，在某些情况下，持久化预构建轮可能是不希望的。例如，在 GitHub Actions 中，省略预构建轮并每次运行时重新下载它们会更快速。但是，缓存从源构建的轮通常更快，因为轮构建过程可能很昂贵，尤其是对于扩展模块。在 --ci 模式下，uv 将从缓存中删除任何预构建轮，但保留任何从源构建的轮。
• --color color-choice
  控制输出中颜色的使用。默认情况下，uv 会自动检测在写入终端时的颜色支持。可能的值：auto：仅在输出将发送到支持颜色终端或 TTY 时启用彩色输出always：无论检测到的环境如何，都启用彩色输出never：禁用彩色输出
• --config-file config-file
  要用于配置的 uv.toml 文件的路径。虽然 uv 配置可以包含在 pyproject.toml 文件中，但在此上下文中不允许。也可以通过 UV_CONFIG_FILE 环境变量设置。
• --directory directory
  在运行命令之前切换到指定的目录。相对路径使用给定的目录作为基础。有关仅更改项目根目录的信息，请参阅 --project。此设置在 uv pip 接口中使用时没有效果。
• --help, -h
  显示此命令的简洁帮助
• --managed-python
  要求使用 uv-managed Python 版本。默认情况下，uv 倾向于使用它管理的 Python 版本。但是，如果没有安装 uv-managed Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。也可以通过 UV_MANAGED_PYTHON 环境变量设置。
• --native-tls
  是否从平台的本地证书存储加载 TLS 证书。默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。webpki-roots 是来自 Mozilla 的可靠信任根集，将其包含在 uv 中可以提高可移植性和性能（尤其是在 macOS 上）。但是，在某些情况下，您可能希望使用平台的本地证书存储，特别是如果您依赖于包含在系统证书存储中的企业信任根（例如，强制代理）。也可以通过 UV_NATIVE_TLS 环境变量设置。
• --no-cache, -n
  避免从缓存读取或写入，而是在操作期间使用临时目录。也可以通过 UV_NO_CACHE 环境变量设置。
• --no-config
  避免发现配置文件（pyproject.toml、uv.toml）。通常，配置文件会在当前目录、父目录或用户配置目录中找到。也可以通过 UV_NO_CONFIG 环境变量设置。
• --no-managed-python
  禁用 uv-managed Python 版本的使用。相反，uv 将在系统上搜索合适的 Python 版本。也可以通过 UV_NO_MANAGED_PYTHON 环境变量设置。
• --no-progress
  隐藏所有进度输出。例如，旋转器或进度条。也可以通过 UV_NO_PROGRESS 环境变量设置。
• --no-python-downloads
  禁用 Python 的自动下载。
• --offline
  禁用网络访问。当禁用时，uv 将仅使用本地缓存数据和本地可用的文件。也可以通过 UV_OFFLINE 环境变量设置。
• --project project
  在给定的项目目录中运行命令。所有 pyproject.toml、uv.toml 和 .python-version 文件将通过从项目根目录向上遍历目录树来找到，以及项目的虚拟环境（.venv）。其他命令行参数（如相对路径）将相对于当前工作目录解析。有关完全更改工作目录的信息，请参阅 --directory。此设置在 uv pip 接口中使用时没有效果。
• --quiet, -q
  不打印任何输出
• --verbose, -v
  使用详细输出。您可以使用 RUST_LOG 环境变量配置细粒度日志记录。（https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives）
• --version, -V
  显示 uv 版本

---

uv 缓存目录

显示缓存目录。

默认情况下，缓存存储在 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]

---

选项

• --allow-insecure-host allow-insecure-host
  允许与主机的不安全连接。可以多次提供。预期接收主机名（例如，localhost）、主机-端口对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：包含在此列表中的主机将不会与系统的证书存储进行验证。仅在安全网络和验证源中使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您面临中间人攻击。也可以通过 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
  显示此命令的简洁帮助
• --managed-python
  要求使用 uv-managed Python 版本。默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv-managed Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。也可以通过 UV_MANAGED_PYTHON 环境变量设置。
• --native-tls
  是否从平台的本地证书存储中加载 TLS 证书。默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。webpki-roots 是来自 Mozilla 的可靠信任根集合，将其包含在 uv 中可以提高可移植性和性能（尤其是在 macOS 上）。但是，在某些情况下，您可能希望使用平台的本地证书存储，特别是如果您依赖于包含在系统证书存储中的企业信任根（例如，强制代理），则更是如此。也可以通过 UV_NATIVE_TLS 环境变量设置。
• --no-cache, -n
  避免从缓存中读取或写入，而是在操作期间使用临时目录。也可以通过 UV_NO_CACHE 环境变量设置。
• --no-config
  避免发现配置文件（pyproject.toml、uv.toml）。通常，配置文件会在当前目录、父目录或用户配置目录中查找。也可以通过 UV_NO_CONFIG 环境变量设置。
• --no-managed-python
  禁用 uv-managed Python 版本的使用。相反，uv 将在系统上搜索合适的 Python 版本。也可以通过 UV_NO_MANAGED_PYTHON 环境变量设置。
• --no-progress
  隐藏所有进度输出。例如，旋转器或进度条。也可以通过 UV_NO_PROGRESS 环境变量设置。
• --no-python-downloads
  禁用 Python 的自动下载。
• --offline
  禁用网络访问。当禁用时，uv 将仅使用本地缓存数据和本地可用文件。也可以通过 UV_OFFLINE 环境变量设置。
• --project project
  在给定的项目目录中运行命令。所有 pyproject.toml、uv.toml 和 .python-version 文件将通过从项目根目录向上遍历目录树来查找，同样还有项目的虚拟环境（.venv）。其他命令行参数（如相对路径）将以当前工作目录为基准解析。有关完全更改工作目录的信息，请参阅 --directory。当在 uv pip 接口中使用时，此设置没有效果。
• --quiet, -q
  不打印任何输出
• --verbose, -v
  使用详细输出。您可以使用 RUST_LOG 环境变量配置细粒度日志记录。（https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives）
• --version, -V
  显示 uv 版本

---

uv 自身

管理 uv 可执行文件

---

使用方法

uv self [OPTIONS] <COMMAND>

---

命令

• uv self update
  更新 uv

---

uv 自更新

更新 uv

---

使用方法

uv self update [OPTIONS] [TARGET_VERSION]

---

参数

• TARGET_VERSION
  更新到指定的版本。如果未提供，uv 将更新到最新版本

---

选项

• --allow-insecure-host allow-insecure-host
  允许与主机的不安全连接。可以多次提供。期望接收主机名（例如，localhost）、主机端口对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：此列表中的主机将不会与系统的证书存储进行验证。仅在安全网络且来源经过验证的情况下使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您面临中间人攻击。也可以通过 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 在向终端或支持颜色的 TTY 写入时会自动检测颜色支持。可能的值：auto：仅在输出将发送到终端或支持颜色的 TTY 时启用彩色输出always：无论检测到的环境如何，都启用彩色输出never：禁用彩色输出
• --config-file config-file
  用于配置的 uv.toml 文件的路径。虽然 uv 配置可以包含在 pyproject.toml 文件中，但在此上下文中不允许。也可以通过 UV_CONFIG_FILE 环境变量设置。
• --directory directory
  在运行命令之前切换到指定的目录。相对路径使用给定目录作为基准。有关仅更改项目根目录的信息，请参阅 --project。参见 --directory 以完全更改工作目录。此设置在 uv pip 接口中使用时没有效果。
• --help, -h
  显示此命令的简洁帮助信息
• --managed-python
  要求使用 uv-managed Python 版本。默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv-managed Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。也可以通过 UV_MANAGED_PYTHON 环境变量设置。
• --native-tls
  是否从平台的本机证书存储加载 TLS 证书。默认情况下，uv 从捆绑的 webpki-roots crate 加载证书。webpki-roots 是来自 Mozilla 的可靠信任根集，将其包含在 uv 中可以提高可移植性和性能（尤其是在 macOS 上）。但是，在某些情况下，您可能希望使用平台的本机证书存储，特别是如果您依赖于包含在系统证书存储中的企业信任根（例如，强制代理），则更是如此。也可以通过 UV_NATIVE_TLS 环境变量设置。
• --no-cache, -n
  避免从缓存中读取或写入，而是在整个操作期间使用临时目录。也可以通过 UV_NO_CACHE 环境变量设置。
• --no-config
  避免发现配置文件（pyproject.toml、uv.toml）。通常，配置文件会在当前目录、父目录或用户配置目录中发现。也可以通过 UV_NO_CONFIG 环境变量设置。
• --no-managed-python
  禁用 uv-managed Python 版本的使用。相反，uv 将在系统上搜索合适的 Python 版本。也可以通过 UV_NO_MANAGED_PYTHON 环境变量设置。
• --no-progress
  隐藏所有进度输出。例如，旋转器或进度条。也可以通过 UV_NO_PROGRESS 环境变量设置。
• --no-python-downloads
  禁用 Python 的自动下载。
• --offline
  禁用网络访问。当禁用时，uv 只会使用本地缓存的数据和本地可用的文件。也可以通过 UV_OFFLINE 环境变量设置。
• --project project
  在给定的项目目录中运行命令。所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历目录树来发现，项目虚拟环境（.venv）也是如此。其他命令行参数（如相对路径）将相对于当前工作目录解析。有关更改整个工作目录的信息，请参阅 --directory。在 uv pip 接口中使用时，此设置没有效果。参见 --directory 以完全更改工作目录。
• --quiet, -q
  不打印任何输出
• --token token
  用于身份验证的 GitHub token。token 不是必需的，但可以用来减少遇到速率限制的可能性。也可以通过 UV_GITHUB_TOKEN 环境变量设置。
• --verbose, -v
  使用详细输出。您可以使用 RUST_LOG 环境变量配置细粒度日志记录。（https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives）
• --version, -V
  显示 uv 版本

---

uv 版本

显示 uv 的版本

---

使用方法

uv version [OPTIONS]

---

选项

• --allow-insecure-host allow-insecure-host
  允许与主机的不安全连接。可以多次提供。预期接收主机名（例如，localhost）、主机-端口号对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：列入此列表的主机将不会与系统的证书存储进行验证。仅在安全网络且来源已验证的情况下使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您面临中间人攻击。还可以通过 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。此设置在 uv pip 接口中使用时没有效果。
• --help, -h
  显示此命令的简洁帮助
• --managed-python
  要求使用 uv-managed Python 版本。默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv-managed Python，它将使用系统 Python 版本。此选项禁用系统 Python 版本的使用。还可以通过 UV_MANAGED_PYTHON 环境变量设置。
• --native-tls
  是否从平台的本地证书存储加载 TLS 证书。默认情况下，uv 从捆绑的 webpki-roots 载件包加载证书。webpki-roots 是来自 Mozilla 的可靠的一组信任根，将它们包含在 uv 中可以提高可移植性和性能（尤其是在 macOS 上）。但是，在某些情况下，您可能想使用平台的本地证书存储，尤其是如果您依赖于包含在系统证书存储中的企业信任根（例如，对于强制代理），则可能更想使用它。还可以通过 UV_NATIVE_TLS 环境变量设置。
• --no-cache, -n
  避免从缓存中读取或写入，而是在操作期间使用临时目录。还可以通过 UV_NO_CACHE 环境变量设置。
• --no-config
  避免发现配置文件（pyproject.toml、uv.toml）。通常，配置文件会在当前目录、父目录或用户配置目录中发现。还可以通过 UV_NO_CONFIG 环境变量设置。
• --no-managed-python
  禁用 uv-managed Python 版本的使用。相反，uv 将在系统上搜索合适的 Python 版本。还可以通过 UV_NO_MANAGED_PYTHON 环境变量设置。
• --no-progress
  隐藏所有进度输出。例如，旋转器或进度条。还可以通过 UV_NO_PROGRESS 环境变量设置。
• --no-python-downloads
  禁用 Python 的自动下载。
• --offline
  禁用网络访问。当禁用时，uv 将仅使用本地缓存的数据和本地可用的文件。还可以通过 UV_OFFLINE 环境变量设置。
• --output-format output-format
• --project project
  在给定的项目目录中运行命令。所有 pyproject.toml、uv.toml 和 .python-version 文件都将通过从项目根目录向上遍历目录树来发现，以及项目的虚拟环境（.venv）。其他命令行参数（如相对路径）将相对于当前工作目录解析。有关完全更改工作目录的信息，请参阅 --directory。此设置在 uv pip 接口中使用时没有效果。
• --quiet, -q
  不打印任何输出
• --verbose, -v
  使用详细输出。您可以使用 RUST_LOG 环境变量配置细粒度日志记录。（https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives）
• --version, -V
  显示 uv 版本

---

uv generate-shell-completion

生成 shell 完成脚本

---

使用方法

uv generate-shell-completion [OPTIONS] <SHELL>

---

参数

• SHELL
  生成完成脚本所需的shell

---

选项

• --allow-insecure-host allow-insecure-host
  允许与主机的不安全连接。可以多次提供。预期接收主机名（例如，localhost）、主机端口对（例如，localhost:8080）或 URL（例如，https://localhost）。警告：包含在此列表中的主机将不会与系统的证书存储进行验证。仅在安全网络中且来源已验证的情况下使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您容易受到中间人攻击。也可以通过 UV_INSECURE_HOST 环境变量来设置。
• --directory directory
  在运行命令之前切换到指定的目录。相对路径以给定目录为基础进行解析。有关仅更改项目根目录的信息，请参阅 --project。
• --managed-python
  要求使用 uv-managed Python 版本。默认情况下，uv 优先使用它管理的 Python 版本。但是，如果没有安装 uv-managed Python，它将使用系统 Python 版本。此选项禁用了系统 Python 版本的使用。也可以通过 UV_MANAGED_PYTHON 环境变量来设置。
• --no-managed-python
  禁用 uv-managed Python 版本的使用。相反，uv 将在系统上搜索合适的 Python 版本。也可以通过 UV_NO_MANAGED_PYTHON 环境变量来设置。
• --project project
  在指定的项目目录中运行命令。所有 pyproject.toml、uv.toml 和 .python-version 文件将通过从项目根目录向上遍历目录树来发现，项目虚拟环境（.venv）也是如此。其他命令行参数（如相对路径）将以当前工作目录为基准进行解析。有关完全更改工作目录的信息，请参阅 --directory。此设置在 uv pip 接口中使用时没有效果。

---

uv 帮助

显示命令的文档

---

使用方法

uv help [OPTIONS] [COMMAND]...

---

参数

• COMMAND

---

---

设置

---

项目元数据

---

build-constraint-dependencies

在解决构建依赖时应用的约束。

构建约束用于在解析或安装过程中构建包时选择构建依赖的版本进行限制。

将包作为约束包含在内 不会 触发在构建过程中安装该包；相反，必须在项目的构建依赖图的其他部分请求该包。

---

注意：在 uv lock、uv sync 和 uv run 中，uv 只会从工作区根目录的 pyproject.toml 中读取 build-constraint-dependencies，并忽略其他工作区成员或 uv.toml 文件中的任何声明。
默认值： []
类型: list[str]
示例用法：
pyproject.toml

[tool.uv]
# Ensure that the setuptools v60.0.0 is used whenever a package has a build dependency
# on setuptools.
build-constraint-dependencies = ["setuptools==60.0.0"]

---

---

conflicts

声明一组冲突的额外依赖或依赖分组（即互斥的）。

当两个或多个额外依赖互不兼容时，声明冲突非常有用。例如，额外依赖 foo 可能依赖于 numpy==2.0.0，而额外依赖 bar 则依赖于 numpy==2.1.0。虽然这些依赖冲突，但可能用户不会同时激活 foo 和 bar，这使得即使在兼容性不匹配的情况下，也可能为项目生成一个通用的解决方案。

通过明确声明这种冲突，uv 可以为项目生成一个通用的解决方案，考虑到某些额外依赖和分组的组合是互斥的。作为交换，如果用户尝试激活两个冲突的额外依赖，则安装将失败。

默认值：[]

类型：list[list[dict]]

示例用法：

pyproject.toml

[tool.uv]
# Require that `package[extra1]` and `package[extra2]` are resolved
# in different forks so that they cannot conflict with one another.
conflicts = [
    [
        { extra = "extra1" },
        { extra = "extra2" },
    ]
]

# Require that the dependency groups `group1` and `group2`
# are resolved in different forks so that they cannot conflict
# with one another.
conflicts = [
    [
        { group = "group1" },
        { group = "group2" },
    ]
]

---

---

constraint-dependencies

在解析项目的依赖项时应用的约束。

约束用于限制在解析过程中选择的依赖项的版本。

将一个包作为约束包括在内 不会 触发该包的安装；相反，该包必须在项目的第一方或传递依赖项的其他地方请求。

---

注意：在 uv lock、uv sync 和 uv run 中，uv 只会从工作区根目录的 pyproject.toml 中读取 constraint-dependencies，并将忽略其他工作区成员或 uv.toml 文件中的任何声明。
默认值： []
类型: list[str]
示例用法：
pyproject.toml

[tool.uv]
# Ensure that the grpcio version is always less than 1.65, if it's requested by a
# direct or transitive dependency.
constraint-dependencies = ["grpcio<1.65"]

---

---

default-groups

默认安装的 dependency-groups 列表。

也可以是字面量 “all”，以默认启用所有组。

默认值： ["dev"]

类型： str | list[str]

示例用法：

pyproject.toml

[tool.uv]
default-groups = ["docs"]

---

---

dev-dependencies

项目的发展依赖。

在 uv run 和 uv sync 中默认安装开发依赖，但不会出现在项目的发布元数据中。

不再推荐使用此字段。相反，使用 dependency-groups.dev 字段，这是一个声明开发依赖的标准方式。tool.uv.dev-dependencies 和 dependency-groups.dev 的内容合并以确定 dev 依赖组的最终需求。

默认值：[]

类型：list[str]

示例用法：

pyproject.toml

[tool.uv]
dev-dependencies = ["ruff==0.5.0"]

---

---

环境

支持环境的列表，用于解析依赖。

默认情况下，uv 会在 uv lock 操作期间解析所有可能的环境。然而，您可以限制支持环境的集合以提高性能并避免解空间中的不满足分支。

当使用 --universal 标志调用 uv pip compile 时，这些环境也将得到尊重。

默认值：[]

类型：str | list[str]

示例用法：

pyproject.toml

[tool.uv]
# Resolve for macOS, but not for Linux or Windows.
environments = ["sys_platform == 'darwin'"]

---

---

index

当解析依赖关系时使用的索引。

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

索引按定义的顺序考虑，这意味着首先定义的索引具有最高优先级。此外，此设置提供的索引优先级高于通过index_url或extra_index_url指定的任何索引。uv只会考虑包含给定包的第一个索引，除非指定了替代的索引策略。

如果一个索引被标记为explicit = true，它将仅用于通过 [tool.uv.sources]显式选择它的依赖项，例如：

[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cu121"
explicit = true

[tool.uv.sources]
torch = { index = "pytorch" }

---

如果索引被标记为 default = true，它将被移动到优先级列表的末尾，这样在解决包时它将获得最低优先级。此外，将索引标记为默认将禁用 PyPI 默认索引。
默认值： []
类型: dict
示例用法：
pyproject.toml

[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cu121"

---

---

managed

项目是否由 uv 管理。如果 false，则在调用 uv run 时 uv 将忽略该项目。

默认值： true

类型： bool

示例用法：

pyproject.toml

[tool.uv]
managed = false

---

---

override-dependencies

当解析项目的依赖项时应用的覆盖。

覆盖用于强制选择特定版本的包，无论其他任何包请求的版本如何，也不管选择该版本通常是否构成无效解析。

虽然约束是 累加的，即它们与构成包的要求相结合，但覆盖是 绝对的，即它们完全取代了任何构成包的要求。

将包作为覆盖包括在内将 不会 触发该包的安装；相反，该包必须在项目的一级或传递依赖项的其他地方请求。

---

注意：在 uv lock、uv sync 和 uv run 中，uv 只会从工作区根目录的 pyproject.toml 中读取 override-dependencies，并忽略其他工作区成员或 uv.toml 文件中的任何声明。
默认值： []
类型: list[str]
示例用法：
pyproject.toml

[tool.uv]
# Always install Werkzeug 2.3.0, regardless of whether transitive dependencies request
# a different version.
override-dependencies = ["werkzeug==2.3.0"]

---

---

package

项目是否应被视为一个 Python 包，或一个非包（“虚拟”）项目。

包在虚拟环境中以可编辑模式构建和安装，因此需要一个构建后端，而虚拟项目则 不是 构建或安装；相反，仅包括它们的依赖项在虚拟环境中。

创建一个包需要在 pyproject.toml 中存在 build-system，并且项目遵守构建后端的期望结构（例如，src 布局）。

默认值： true

类型： bool

示例用法：

pyproject.toml

[tool.uv]
package = false

---

---

required-environments

所需平台的列表，适用于缺少源分发的软件包。

当一个软件包没有源分发时，它的可用性将限于其构建分发（wheels）所支持的平台。例如，如果一个软件包只为 Linux 发布 wheels，那么它将无法在 macOS 或 Windows 上安装。

默认情况下，uv 要求每个软件包至少包含一个与指定 Python 版本兼容的 wheel。可以使用 required-environments 设置来确保结果解析包含特定平台的 wheels，或者如果没有此类 wheels 则失败。

虽然 environments 设置 限制 uv 在解析依赖时考虑的环境集，但 required-environments 扩展 uv 在解析依赖时必须支持的平台集。

例如，environments = ["sys_platform == 'darwin'"] 将将 uv 限制为仅解决 macOS（并忽略 Linux 和 Windows）。另一方面，required-environments = ["sys_platform == 'darwin'"] 将 要求 任何没有源分发的软件包包含一个适用于 macOS 的 wheel 才能安装。

默认值：[]

类型：str | list[str]

示例用法：

pyproject.toml

[tool.uv]
# Require that the package is available for macOS ARM and x86 (Intel).
required-environments = [
    "sys_platform == 'darwin' and platform_machine == 'arm64'",
    "sys_platform == 'darwin' and platform_machine == 'x86_64'",
]

---

---

sources

使用时解析依赖项的源。

tool.uv.sources 在开发过程中丰富了依赖项元数据，并添加了额外的源。依赖项源可以是 Git 仓库、URL、本地路径或替代注册表。

有关更多信息，请参阅依赖项。

默认值： {}

类型： dict

示例用法：

pyproject.toml

[tool.uv.sources]
httpx = { git = "https://github.com/encode/httpx", tag = "0.27.0" }
pytest = { url = "https://files.pythonhosted.org/packages/6b/77/7440a06a8ead44c7757a64362dd22df5760f9b12dc5f11b6188cd2fc27a0/pytest-8.3.3-py3-none-any.whl" }
pydantic = { path = "/path/to/pydantic", editable = true }

---

---

工作区

---

exclude

要排除的工作区成员的包。如果一个包同时匹配 members 和 exclude，则将被排除。

支持glob和显式路径。

有关glob语法的更多信息，请参阅《glob文档》。

默认值：[]

类型：list[str]

示例用法：

pyproject.toml

[tool.uv.workspace]
exclude = ["member1", "path/to/member2", "libs/*"]

---

---

members

包含在工作区成员中的包。

支持通配符和显式路径。

有关通配符语法的更多信息，请参阅glob 文档。

默认值： []

类型： list[str]

示例用法：

pyproject.toml

[tool.uv.workspace]
members = ["member1", "path/to/member2", "libs/*"]

---

---

配置

---

allow-insecure-host

允许不安全的连接到主机。

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

警告：此列表中的主机将不会与系统的证书存储进行验证。仅在安全网络中带有验证源的情况下使用 --allow-insecure-host，因为它绕过了 SSL 验证，可能会使您面临中间人攻击。

默认值：[]

类型：list[str]

示例用法：

pyproject.tomluv.toml

[tool.uv]
allow-insecure-host = ["localhost:8080"]

---

---

cache-dir

缓存目录的路径。

默认为 Linux 和 macOS 上的 $XDG_CACHE_HOME/uv 或 $HOME/.cache/uv，以及 Windows 上的 %LOCALAPPDATA%\uv\cache。

默认值: None

类型: str

示例用法:

pyproject.tomluv.toml

[tool.uv]
cache-dir = "./.uv_cache"

---

---

cache-keys

在缓存项目构建时需要考虑的键。

缓存键允许您指定在修改时应触发重建的文件或目录。默认情况下，uv 将在项目目录中的 pyproject.toml、setup.py 或 setup.cfg 文件被修改，或者添加或删除 src 目录时重建项目，即：

cache-keys = [{ file = "pyproject.toml" }, { file = "setup.py" }, { file = "setup.cfg" }, { dir = "src" }]

---

作为一个例子：如果一个项目使用动态元数据从 requirements.txt 文件中读取其依赖项，你可以指定 cache-keys = [{ file = "requirements.txt" }, { file = "pyproject.toml" }] 以确保在修改 requirements.txt 文件时（除了监视 pyproject.toml）项目会重新构建。

Globs 被支持，遵循 glob crate 的语法。例如，每当项目目录或其子目录中的 .toml 文件被修改时，您可以通过指定 cache-keys = [{ file = "**/*.toml" }] 来使缓存失效。请注意，使用 globs 可能会非常昂贵，因为 uv 可能需要遍历文件系统来确定是否有任何文件已更改。
缓存键也可以包含版本控制信息。

例如，如果一个项目使用 setuptools_scm 从 Git 提交中读取其版本，你可以指定 cache-keys = [{ git = { commit = true }, { file = "pyproject.toml" }] 以在缓存键中包含当前的 Git 提交哈希（除了 pyproject.toml）。

Git 标签也通过 cache-keys = [{ git = { commit = true, tags = true } }] 支持。
缓存键也可以包含环境变量。

例如，如果项目依赖于 MACOSX_DEPLOYMENT_TARGET 或其他环境变量来确定其行为，您可以通过指定 cache-keys = [{ env = "MACOSX_DEPLOYMENT_TARGET" }] 来在环境变量更改时使缓存失效。
缓存键仅影响它们指定的 pyproject.toml 定义的工程（与例如影响工作空间中的所有成员相反），并且所有路径和通配符都被解释为相对于项目目录的相对路径。

默认值：[{ file = "pyproject.toml" }, { file = "setup.py" }, { file = "setup.cfg" }]

类型: list[dict]

示例用法：
pyproject.toml

cache-keys = [{ file = "pyproject.toml" }, { file = "setup.py" }, { file = "setup.cfg" }, { dir = "src" }]

---

---

check-url

检查索引 URL 以跳过重复的上传。

此选项允许重试只上传了一部分但并非全部文件后失败的发布，并处理由于同一文件的并行上传导致的错误。

在上传之前，会检查索引。如果索引中已经存在完全相同的文件，则不会上传该文件。如果在上传过程中发生错误，则会再次检查索引，以处理在并行上传过程中相同文件被上传两次的情况。

具体行为将根据索引而有所不同。当上传到 PyPI 时，即使没有 --check-url，上传相同的文件也会成功，而大多数其他索引会报错。

索引必须提供支持的哈希之一（SHA-256、SHA-384 或 SHA-512）。

默认值：None

类型：str

示例用法：

pyproject.tomluv.toml

[tool.uv]
check-url = "https://test.pypi.org/simple"

---

---

compile-bytecode

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

默认情况下，uv 不会在安装时将 Python (.py) 文件编译为字节码 (__pycache__/*.pyc)；相反，它会在首次导入模块时懒惰地执行编译。对于启动时间至关重要的用例，例如 CLI 应用程序和 Docker 容器，此选项可以被启用，以牺牲较长的安装时间为换取更快的启动时间。

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

默认值：false

类型：bool

示例用法：

pyproject.tomluv.toml

[tool.uv]
compile-bytecode = true

---

---

concurrent-builds

uv在任何给定时间将构建的最大源分发数量。

默认为可用的CPU核心数。

默认值：None

类型：int

示例用法：

pyproject.tomluv.toml

[tool.uv]
concurrent-builds = 4

---

---

并发下载

在任何给定时间内，uv 将执行的最大并发下载数。

默认值：50

类型：int

示例用法：

pyproject.tomluv.toml

[tool.uv]
concurrent-downloads = 4

---

---

并发安装

安装和解压软件包时使用的线程数。

默认值为可用的CPU核心数。

默认值： None

类型： int

示例用法：

pyproject.tomluv.toml

[tool.uv]
concurrent-installs = 4

---

---

config-settings

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

默认值： {}

类型： dict

示例用法：

pyproject.tomluv.toml

[tool.uv]
config-settings = { editable_mode = "compat" }

---

---

dependency-metadata

项目依赖项的预定义静态元数据（直接或间接）。当提供时，允许解析器使用指定的元数据而不是查询注册表或从源构建相关包。

元数据应遵循 Metadata 2.3 标准，尽管只有以下字段被尊重：

• name：包的名称。
• （可选）version：包的版本。如果省略，则元数据将应用于包的所有版本。
• （可选）requires-dist：包的依赖项（例如，werkzeug>=0.14）。
• （可选）requires-python：包所需的 Python 版本（例如，>=3.10）。
• （可选）provides-extras：包提供的额外内容。

默认值：[]

类型：list[dict]

示例用法：

pyproject.tomluv.toml

[tool.uv]
dependency-metadata = [
    { name = "flask", version = "1.0.0", requires-dist = ["werkzeug"], requires-python = ">=3.6" },
]

---

---

exclude-newer

限制候选软件包，仅限于在给定日期之前上传的软件包。

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

默认值：None

类型：str

示例用法：

pyproject.tomluv.toml

[tool.uv]
exclude-newer = "2006-12-02"

---

---

extra-index-url

额外的包索引 URL，除了 --index-url 之外。

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

通过此标志提供的所有索引都优先于由 index_url 或 index（默认值为 true）指定的索引。当提供多个索引时，较早的值优先。

要控制 uv 在存在多个索引时的解析策略，请参阅 index_strategy（https://docs.astral.sh/uv/reference/settings/#index-strategy）。

（已弃用：请使用 index 代替。）

默认值：[]

类型：list[str]

示例用法：

pyproject.tomluv.toml

[tool.uv]
extra-index-url = ["https://download.pytorch.org/whl/cpu"]

---

---

find-links

搜索候选分发的位置，除了在注册表索引中找到的之外。

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

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

默认值：[]

类型：list[str]

示例用法：

pyproject.tomluv.toml

[tool.uv]
find-links = ["https://download.pytorch.org/whl/torch_stable.html"]

---

---

fork-strategy

选择给定软件包在 Python 版本和平台之间的多个版本时所使用的策略。

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

在 fewest 模式下，uv 将最小化每个软件包选择的版本数量，优先选择与更广泛的受支持 Python 版本或平台兼容的较旧版本。

默认值："requires-python"

可能的值：

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

示例用法：

pyproject.tomluv.toml

[tool.uv]
fork-strategy = "fewest"

---

---

index

在解决依赖关系时使用的包索引。

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

索引将按照定义的顺序考虑，这意味着首先定义的索引具有最高的优先级。此外，此设置提供的索引比通过 index_url 或 extra_index_url 指定的任何索引都具有更高的优先级。uv 将仅考虑包含给定包的第一个索引，除非指定了替代的 索引策略。

如果索引被标记为 explicit = true，它将仅用于那些通过 [tool.uv.sources] 明确选择它的依赖项，例如：

[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cu121"
explicit = true

[tool.uv.sources]
torch = { index = "pytorch" }

---

如果索引被标记为 default = true，它将被移动到优先列表的末尾，这样在解决包时它将获得最低优先级。此外，将索引标记为默认将禁用 PyPI 默认索引。
默认值："[]"
类型: dict
示例用法：
pyproject.tomluv.toml

[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cu121"

---

---

index-strategy

解决多个索引 URL 时使用的策略。

默认情况下，uv 将在第一个包含给定包的索引处停止，并将解析限制在那些出现在该第一个索引上的包上（first-index）。这可以防止“依赖混淆”攻击，攻击者可以在备用索引下上传具有相同名称的恶意包。

默认值："first-index"

可能的值：

• "first-index"：仅使用第一个索引返回匹配给定包名称的结果
• "unsafe-first-match"：在所有索引中搜索每个包名称，在移动到下一个索引之前耗尽第一个索引的版本
• "unsafe-best-match"：在所有索引中搜索每个包名称，优先考虑找到的“最佳”版本。如果包版本在多个索引中，则只查看第一个索引的条目

示例用法：

pyproject.tomluv.toml

[tool.uv]
index-strategy = "unsafe-best-match"

---

---

index-url

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

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

此设置提供的索引优先级低于通过 extra_index_url（uv.toml）或 index（uv.toml）指定的任何索引。

（已弃用：请使用 index 代替。）

默认值："https://pypi.org/simple"

类型：str

示例用法：

pyproject.tomluv.toml

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

---

---

keyring-provider

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

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

默认值："disabled"

类型：str

示例用法：

pyproject.tomluv.toml

[tool.uv]
keyring-provider = "subprocess"

---

---

link-mode

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

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

默认值："clone"（macOS）或 "hardlink"（Linux，Windows）

可能的值:

• "clone"：从 wheel 复制（即写时复制）软件包到 site-packages 目录
• "copy"：将软件包从 wheel 复制到 site-packages 目录
• "hardlink"：从 wheel 创建到 site-packages 目录的硬链接
• "symlink"：从 wheel 创建到 site-packages 目录的符号链接

示例用法:

pyproject.tomluv.toml

[tool.uv]
link-mode = "copy"

---

---

native-tls

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

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

然而，在某些情况下，您可能希望使用平台的本地证书存储，尤其是如果您依赖于系统证书存储中包含的企业的信任根（例如，对于强制代理）。

默认值：false

类型：bool

示例用法：

pyproject.tomluv.toml

[tool.uv]
native-tls = true

---

---

no-binary

不安装预编译的wheels。

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

默认值：false

类型：bool

示例用法：

pyproject.tomluv.toml

[tool.uv]
no-binary = true

---

---

no-binary-package

不要为特定包安装预构建的轮子。

默认值: []

类型: list[str]

示例用法:

pyproject.tomluv.toml

[tool.uv]
no-binary-package = ["ruff"]

---

---

no-build

不要构建源分发版。

当启用时，解析将不会运行任意的Python代码。将重用已构建的源分发版的缓存的wheel文件，但需要构建分发版的操作将退出并显示错误。

默认值：false

类型：bool

示例用法：

pyproject.tomluv.toml

[tool.uv]
no-build = true

---

---

no-build-isolation

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

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

默认值：false

类型：bool

示例用法：

pyproject.tomluv.toml

[tool.uv]
no-build-isolation = true

---

---

no-build-isolation-package

在构建特定包的源分发版时禁用隔离。

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

默认值： []

类型： list[str]

示例用法：

pyproject.tomluv.toml

[tool.uv]
no-build-isolation-package = ["package1", "package2"]

---

---

no-build-package

不要为特定包构建源代码分布。

默认值：[]

类型：list[str]

示例用法：

pyproject.tomluv.toml

[tool.uv]
no-build-package = ["ruff"]

---

---

no-cache

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

默认值：false

类型：bool

示例用法：

pyproject.tomluv.toml

[tool.uv]
no-cache = true

---

---

no-index

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

默认值： false

类型： bool

示例用法：

pyproject.tomluv.toml

[tool.uv]
no-index = true

---

---

no-sources

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

默认值：false

类型：bool

示例用法：

pyproject.tomluv.toml

[tool.uv]
no-sources = true

---

---

offline

禁用网络访问，仅依赖本地缓存数据和本地可用的文件。

默认值：false

类型：bool

示例用法：

pyproject.tomluv.toml

[tool.uv]
offline = true

---

---

prerelease

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

默认情况下，uv 将接受只发布预发布版本的包的预发布版本，以及包含在声明的规范中（if-necessary-or-explicit）显式预发布标记的第三方要求。

默认值："if-necessary-or-explicit"

可能的值:

• "disallow"：禁止所有预发布版本
• "allow"：允许所有预发布版本
• "if-necessary"：如果包的所有版本都是预发布版本，则允许预发布版本
• "explicit"：允许具有其版本要求中显式预发布标记的第三方包的预发布版本
• "if-necessary-or-explicit"：如果包的所有版本都是预发布版本，或者包在其版本要求中具有显式预发布标记，则允许预发布版本

示例用法:

pyproject.tomluv.toml

[tool.uv]
prerelease = "allow"

---

---

preview

是否启用实验性、预览功能。

默认值：false

类型：bool

示例用法：

pyproject.tomluv.toml

[tool.uv]
preview = true

---

---

publish-url

发布包到 Python 包索引的 URL（默认为：https://upload.pypi.org/legacy/）。

默认值："https://upload.pypi.org/legacy/"

类型：str

示例用法：

pyproject.tomluv.toml

[tool.uv]
publish-url = "https://test.pypi.org/legacy/"

---

---

pypy-install-mirror

用于下载管理 PyPy 安装的镜像 URL。

默认情况下，管理 PyPy 安装是从 downloads.python.org 下载的。此变量可以设置为一个镜像 URL 以使用不同的源来下载 PyPy 安装。提供的 URL 将替换 https://downloads.python.org/pypy 中的内容，例如，在 https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2 中。

可以通过使用 file:// URL 方案从本地目录读取发行版。

默认值： None

类型： str

示例用法：

pyproject.tomluv.toml

[tool.uv]
pypy-install-mirror = "https://downloads.python.org/pypy"

---

---

python-downloads

是否允许下载 Python。

默认值："automatic"

可能的值：

• "automatic"：当需要时自动下载管理的 Python 安装
• "manual"：不要自动下载管理的 Python 安装；需要显式安装
• "never"：永远不允许下载 Python

示例用法：

pyproject.tomluv.toml

[tool.uv]
python-downloads = "manual"

---

---

python-install-mirror

Python 安装镜像 URL。

默认情况下，受管理的 Python 安装是从 python-build-standalone 下载的。此变量可以设置为一个镜像 URL 以使用不同的 Python 安装源。提供的 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 方案从本地目录读取发行版。

默认值： None

类型： str

示例用法：

pyproject.tomluv.toml

[tool.uv]
python-install-mirror = "https://github.com/astral-sh/python-build-standalone/releases/download"

---

---

python-preference

是否优先使用系统中已存在的 Python 安装，还是那些由 uv 下载和安装的。

默认值："managed"

可能的值：

• "only-managed"：仅使用管理的 Python 安装；从不使用系统 Python 安装
• "managed"：优先使用管理的 Python 安装，而非系统 Python 安装
• "system"：优先使用系统 Python 安装，而非管理的 Python 安装
• "only-system"：仅使用系统 Python 安装；从不使用管理的 Python 安装

示例用法：

pyproject.tomluv.toml

[tool.uv]
python-preference = "managed"

---

---

reinstall

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

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

[tool.uv]
reinstall = true

---

---

reinstall-package

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

默认值：[]

类型：list[str]

示例用法：

pyproject.tomluv.toml

[tool.uv]
reinstall-package = ["ruff"]

---

---

required-version

强制对 uv 版本的要求。

如果 uv 的版本在运行时不满足要求，uv 将以错误退出。

接受一个 PEP 440 规范符，如 ==0.5.0 或 >=0.5.0。

默认值：null

类型：str

示例用法：

pyproject.tomluv.toml

[tool.uv]
required-version = ">=0.5.0"

---

---

分辨率

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

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

默认值："highest"

可能值：

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

示例用法：

pyproject.tomluv.toml

[tool.uv]
resolution = "lowest-direct"

---

---

trusted-publishing

配置通过 GitHub Actions 的可信发布。

默认情况下，uv 在 GitHub Actions 中运行时会检查可信发布，但如果未配置或工作流程权限不足（例如，来自分叉的拉取请求），则会忽略它。

默认值：automatic

类型：str

示例用法：

pyproject.tomluv.toml

[tool.uv]
trusted-publishing = "always"

---

---

升级

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

默认值：false

类型：bool

示例用法：

pyproject.tomluv.toml

[tool.uv]
upgrade = true

---

---

升级包

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

接受独立包名（ruff）和版本指定符（ruff<0.5.0）。

默认值：[]

类型：list[str]

示例用法：

pyproject.tomluv.toml

[tool.uv]
upgrade-package = ["ruff"]

---

---

pip

针对 uv pip 命令行界面的特定设置。

当在 uv pip 命名空间外运行命令时（例如，uv lock，uvx），这些值将被忽略。

---

all-extras

包含所有可选依赖。

仅适用于 pyproject.toml、setup.py 和 setup.cfg 源。

默认值：false

类型：bool

示例用法：

pyproject.tomluv.toml

[tool.uv.pip]
all-extras = true

---

---

allow-empty-requirements

允许使用 uv pip sync 与空要求，这将清除环境中的所有包。

默认值：false

类型：bool

示例用法：

pyproject.tomluv.toml

[tool.uv.pip]
allow-empty-requirements = true

---

---

annotation-style

输出文件中包含的注释样式，用于指示每个包的来源。

默认值："split"

可能的值：

• "line"：在单个、以逗号分隔的行上渲染注释
• "split"：在单独的一行上渲染每个注释

示例用法：

pyproject.tomluv.toml

[tool.uv.pip]
annotation-style = "line"

---

---

break-system-packages

允许 uv 修改一个 EXTERNALLY-MANAGED Python 安装。

警告：--break-system-packages 旨在用于持续集成（CI）环境，当安装到由外部包管理器（如 apt）管理的 Python 安装中时。应谨慎使用，因为此类 Python 安装明确建议不要由其他包管理器（如 uv 或 pip）进行修改。

默认值：false

类型：bool

示例用法：

pyproject.tomluv.toml

[tool.uv.pip]
break-system-packages = true

---

---

编译字节码

在安装后，将 Python 文件编译成字节码。

默认情况下，uv 不会在安装后将 Python (.py) 文件编译成字节码 (__pycache__/*.pyc)；相反，编译会在第一次导入模块时懒惰地执行。对于启动时间至关重要的用例，例如 CLI 应用程序和 Docker 容器，此选项可以启用，以用较长的安装时间换取较快的启动时间。

启用时，uv 将处理整个 site-packages 目录（包括当前操作未修改的包）以确保一致性。像 pip 一样，它也会忽略错误。

默认值：false

类型：bool

示例用法：

pyproject.tomluv.toml

[tool.uv.pip]
compile-bytecode = true

---

---

config-settings

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

默认值： {}

类型： dict

示例用法：

pyproject.tomluv.toml

[tool.uv.pip]
config-settings = { editable_mode = "compat" }

---

---

custom-compile-command

输出文件顶部包含的头部注释，由 uv pip compile 生成。

用于反映自定义构建脚本和命令，这些脚本和命令封装了 uv pip compile。

默认值： None

类型： str

示例用法：

pyproject.tomluv.toml

[tool.uv.pip]
custom-compile-command = "./custom-uv-compile.sh"

---

---

依赖元数据

项目依赖项（直接或传递性）的预定义静态元数据。当提供时，使解析器能够使用指定的元数据而不是查询注册表或从源构建相关包。

元数据应遵守 元数据 2.3 标准，尽管只有以下字段被尊重：

• name：包的名称。
• （可选）version：包的版本。如果省略，元数据将应用于包的所有版本。
• （可选）requires-dist：包的依赖项（例如，werkzeug>=0.14）。
• （可选）requires-python：包所需的 Python 版本（例如，>=3.10）。
• （可选）provides-extras：包提供的额外内容。

默认值：[]

类型：list[dict]

示例用法：

pyproject.tomluv.toml

[tool.uv.pip]
dependency-metadata = [
    { name = "flask", version = "1.0.0", requires-dist = ["werkzeug"], requires-python = ">=3.6" },
]

---

---

emit-build-options

在 uv pip compile 生成的输出文件中包含 --no-binary 和 --only-binary 条目。

默认值：false

类型：bool

示例用法：

pyproject.tomluv.toml

[tool.uv.pip]
emit-build-options = true

---

---

emit-find-links

在由 uv pip compile 生成的输出文件中包含 --find-links 条目。

默认值：false

类型：bool

示例用法：

pyproject.tomluv.toml

[tool.uv.pip]
emit-find-links = true

---

---

emit-index-annotation

包含注释来指示用于解析每个包的索引（例如，# from https://pypi.org/simple）。

默认值：false

类型：bool

示例用法：

pyproject.tomluv.toml

[tool.uv.pip]
emit-index-annotation = true

---

---

emit-index-url

在由 uv pip compile 生成的输出文件中包含 --index-url 和 --extra-index-url 条目。

默认值： false

类型： bool

示例用法：

pyproject.tomluv.toml

[tool.uv.pip]
emit-index-url = true

---

---

emit-marker-expression

是否发出一个标记字符串，以指示固定依赖集有效的条件。

即使标记表达式为假，固定依赖集也可能有效，但当表达式为真时，要求被认为是正确的。

默认值：false

类型：bool

示例用法：

pyproject.tomluv.toml

[tool.uv.pip]
emit-marker-expression = true

---

---

exclude-newer

限制候选包为那些在给定时间点之前上传的包。

接受 RFC 3339 的子集（例如，2006-12-02T02:07:43Z）。需要完整的时间戳以确保解析器在不同时区中表现一致。

默认值： None

类型： str

示例用法：

pyproject.tomluv.toml

[tool.uv.pip]
exclude-newer = "2006-12-02T02:07:43Z"

---

---

extra