工具

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

注意

有关使用工具界面的介绍，请参阅工具指南 — 本文档讨论工具管理的详细信息。

uv tool 接口

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

因为在不安装的情况下运行工具非常常见，所以为 uv tool run 提供了一个 uvx 别名 — 这两个命令完全等效。为简洁起见，文档将主要引用 uvx 而不是 uv tool run。

也可以使用 uv tool install 安装工具，在这种情况下，它们的可执行文件可以在 PATH 上使用 — 仍然使用隔离的虚拟环境，但命令完成后不会删除它。

执行 vs 安装

在大多数情况下，使用 uvx 执行工具比安装工具更合适。如果您需要工具可用于系统上的其他程序，例如，如果您不控制的某些脚本需要该工具，或者您在 Docker 镜像中并且希望使该工具可供用户使用，则安装该工具很有用。

工具环境

使用 uvx 运行工具时，虚拟环境存储在 uv 缓存目录中，并被视为可丢弃的，也就是说，如果您运行 uv cache clean，该环境将被删除。仅缓存环境以减少重复调用的开销。如果环境被删除，将自动创建一个新环境。

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

工具版本

除非请求特定版本，否则 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 工具目录名为 tools，位于 uv 应用程序状态目录中，例如 ~/.local/share/uv/tools。该位置可以使用 UV_TOOL_DIR 环境变量进行自定义。

要显示工具安装目录的路径

$ uv tool dir

工具环境放置在与工具包名称相同的目录中，例如 .../tools/<name>。

重要

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

升级工具

可以通过 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>

如果请求的版本与工具包的要求冲突，则软件包解析将失败并且命令将出错。

Python 版本

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

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

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

工具可执行文件

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

bin 目录

可执行文件按照 XDG 标准安装到用户 bin 目录中，例如 ~/.local/bin。与 uv 中的其他目录方案不同，XDG 标准用于所有平台，特别是包括 Windows 和 macOS — 在这些平台上没有明确的替代位置来放置可执行文件。安装目录由第一个可用的环境变量确定

• $UV_TOOL_BIN_DIR
• $XDG_BIN_HOME
• $XDG_DATA_HOME/../bin
• $HOME/.local/bin

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

PATH

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

覆盖可执行文件

工具的安装不会覆盖先前不是由 uv 安装的 bin 目录中的可执行文件。例如，如果已使用 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。