工具

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

注意

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

uv tool 接口

uv 包含一个用于与工具交互的专用接口。可以使用 uv tool run 无需安装即可调用工具，在这种情况下，其依赖项将安装在与当前项目隔离的临时虚拟环境中。

由于经常会在不安装工具的情况下运行工具，因此为 uv tool run 提供了 uvx 别名，这两个命令完全等效。为简洁起见，文档中大多会使用 uvx 而非 uv tool run。

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

执行与安装

在大多数情况下，使用 uvx 执行工具比安装工具更合适。如果需要让系统上的其他程序也能使用该工具，例如，某个不受您控制的脚本需要该工具，或者您在 Docker 镜像中并希望让用户能够使用该工具，那么安装工具会很有用。

工具环境

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

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

工具版本

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

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

$ uvx ruff@0.6.0 --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 ruff@0.6.0

工具目录

默认情况下，uv 工具目录名为 tools，位于 uv 应用程序状态目录中，例如 ~/.local/share/uv/tools。可以使用 UV_TOOL_DIR 环境变量自定义该位置。

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

$ uv tool dir

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

Important

工具环境不应直接修改。强烈建议不要手动修改工具环境，例如使用 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 设置。

Note

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

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

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

$ uv tool upgrade black --reinstall

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

$ uv tool upgrade black --reinstall-package click

包含额外依赖项

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

$ uvx --with <额外软件包> <工具>

并且，在工具安装期间：

$ uv tool install --with <额外软件包> <工具软件包>

可以多次提供 --with 选项以包含更多软件包。

--with 选项支持软件包规范，因此可以请求特定版本：

$ uvx --with <额外软件包>==<版本> <工具软件包>

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

工具可执行文件

工具可执行文件包括 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

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

覆盖可执行文件

工具安装不会覆盖 bin 目录中之前未由 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。