工具

工具是提供命令行界面的 Python 包。

注意

请参阅 工具指南 以了解如何使用工具界面 —— 本文档将讨论工具管理的细节。

uv tool 界面

uv 包含一个用于与工具交互的专用界面。工具可以在不安装的情况下使用 uv tool run 调用，此时它们的依赖项将被安装在一个与当前项目隔离的临时虚拟环境中。

由于在不安装的情况下运行工具非常普遍，因此提供了一个 uvx 别名来代替 uv tool run —— 这两个命令完全等效。为了简洁起见，本文档主要使用 uvx 而非 uv tool run。

工具也可以使用 uv tool install 进行安装，在这种情况下，它们的可执行文件将 出现在 PATH 中 —— 依然使用隔离的虚拟环境，但该环境在命令完成后不会被移除。

执行与安装

在大多数情况下，使用 uvx 执行工具比安装工具更合适。安装工具适用于以下情况：您需要让系统中的其他程序使用该工具（例如，某些您无法控制的脚本需要该工具），或者您身处 Docker 镜像中并希望向用户提供该工具。

工具环境

当使用 uvx 运行工具时，虚拟环境会被存储在 uv 缓存目录中，并被视为一次性的，即如果您运行 uv cache clean，该环境将被删除。缓存该环境仅是为了减少重复调用的开销。如果环境被移除，将会自动创建一个新的环境。

当使用 uv tool install 安装工具时，虚拟环境会创建在 uv 工具目录 中。除非卸载该工具，否则环境不会被移除。如果手动删除了该环境，工具将无法运行。

重要

工具环境不应该被直接修改。强烈建议永远不要手动更改工具环境，例如使用 pip 操作。

工具版本

除非要求特定版本，否则 uv tool install 将安装请求工具的最新可用版本。uvx 在首次调用时将使用请求工具的最新可用版本。之后，uvx 将使用工具的缓存版本，除非请求了不同版本、缓存被修剪或缓存被刷新。

例如，要运行特定版本的 Ruff：

$ uvx [email protected] --version
ruff 0.6.0

后续调用 uvx 将使用最新版本，而不是缓存版本。

$ uvx ruff --version
ruff 0.6.2

但是，如果发布了新版本的 Ruff，除非刷新缓存，否则不会使用新版本。

要请求最新版本的 Ruff 并刷新缓存，请使用 @latest 后缀：

$ uvx ruff@latest --version
0.6.2

一旦使用 uv tool install 安装了工具，uvx 默认将使用已安装的版本。

例如，在安装旧版本的 Ruff 后：

$ uv tool install ruff==0.5.0

ruff 和 uvx ruff 的版本是一样的。

$ ruff --version
ruff 0.5.0
$ uvx ruff --version
ruff 0.5.0

但是，您可以通过明确请求最新版本来忽略已安装的版本，例如：

$ uvx ruff@latest --version
0.6.2

或者，使用 --isolated 标志，它将避免刷新缓存，但会忽略已安装的版本：

$ uvx --isolated ruff --version
0.6.2

uv tool install 也支持 {package}@{version} 和 {package}@latest 指定符，如下所示：

$ uv tool install ruff@latest
$ uv tool install [email protected]

升级工具

工具环境可以通过 uv tool upgrade 进行升级，或者通过后续的 uv tool install 操作完全重新创建。

要升级工具环境中的所有包：

$ uv tool upgrade black

要升级工具环境中的单个包：

$ uv tool upgrade black --upgrade-package click

工具升级将遵循安装工具时提供的版本约束。例如，uv tool install black >=23,<24 后接 uv tool upgrade black 会将 Black 升级到 >=23,<24 范围内的最新版本。

如果想要替换版本约束，请使用 uv tool install 重新安装该工具：

$ uv tool install black>=24

同样地，工具升级将保留安装工具时提供的设置。例如，uv tool install black --prerelease allow 后接 uv tool upgrade black 将保留 --prerelease allow 设置。

注意

工具升级会重新安装工具的可执行文件，即使它们没有发生变化。

要在升级期间重新安装包，请使用 --reinstall 和 --reinstall-package 选项。

要重新安装工具环境中的所有包：

$ uv tool upgrade black --reinstall

要重新安装工具环境中的单个包：

$ uv tool upgrade black --reinstall-package click

包含额外依赖

在工具执行期间可以包含额外的包：

$ uvx --with <extra-package> <tool>

在工具安装期间也可以：

$ uv tool install --with <extra-package> <tool-package>

--with 选项可以多次提供，以包含多个额外的包。

--with 选项支持包说明符，因此可以请求特定版本：

$ uvx --with <extra-package>==<version> <tool-package>

可以使用 -w 简写来代替 --with 选项：

$ uvx -w <extra-package> <tool-package>

如果请求的版本与工具包的要求冲突，包解析将失败，命令将报错。

从其他包安装可执行文件

安装工具时，您可能希望在同一个工具环境中包含来自其他包的可执行文件。当您有协同工作的相关工具，或者想要安装共享依赖项的多个可执行文件时，这非常有用。

--with-executables-from 选项允许您指定额外的包，其可执行文件将与主工具一起安装：

$ uv tool install --with-executables-from <package1>,<package2> <tool-package>

例如，安装 Ansible 以及来自 ansible-core 和 ansible-lint 的可执行文件：

$ uv tool install --with-executables-from ansible-core,ansible-lint ansible

这会将来自 ansible、ansible-core 和 ansible-lint 包的所有可执行文件安装到同一个工具环境中，使它们全部在 PATH 中可用。

--with-executables-from 选项可以与其他安装选项结合使用。

$ uv tool install --with-executables-from ansible-core --with mkdocs-material ansible

请注意，--with-executables-from 与 --with 的区别在于：

• --with 将额外包作为依赖项包含，但不会安装它们的可执行文件。
• --with-executables-from 既将包作为依赖项包含，又安装它们的可执行文件。

Python 版本

每个工具环境都链接到一个特定的 Python 版本。它使用与 uv 创建的其他虚拟环境相同的 Python 版本发现逻辑，但会忽略非全局的 Python 版本请求，如 .python-version 文件和 pyproject.toml 中的 requires-python 值。

--python 选项可用于请求特定版本。有关详细信息，请参阅 Python 版本 文档。

如果工具所使用的 Python 版本被卸载，工具环境将被破坏，该工具可能无法使用。

工具可执行文件

工具可执行文件包括 Python 包提供的所有控制台入口点、脚本入口点和二进制脚本。工具可执行文件在 Unix 系统上被符号链接到 可执行文件目录，在 Windows 上则会被复制过去。

注意

工具包的依赖项所提供的可执行文件不会被安装。

可执行文件目录必须位于 PATH 环境变量中，工具可执行文件才能在 shell 中直接调用。如果它不在 PATH 中，系统会显示警告。可以使用 uv tool update-shell 命令将可执行文件目录添加到常用 shell 配置文件中的 PATH 中。

覆盖可执行文件

安装工具时，不会覆盖之前不是由 uv 安装的可执行文件。例如，如果已使用 pipx 安装了某个工具，uv tool install 将会失败。可以使用 --force 标志来覆盖此行为。

与 uv run 的关系

调用 uv tool run <name>（或 uvx <name>）大致等同于：

$ uv run --no-project --with <name> -- <name>

然而，使用 uv 的工具界面时有几点显著差异：

• 不需要 --with 选项 —— 所需的包会根据命令名称自动推断。
• 临时环境会被缓存在专用位置。
• 不需要 --no-project 标志 —— 工具运行始终与项目隔离。
• 如果工具已经安装，uv tool run 将使用已安装的版本，而 uv run 则不会。

如果工具不应与项目隔离（例如运行 pytest 或 mypy 时），则应使用 uv run 而不是 uv tool run。