3.11 工具

原文链接: https://docs.astral.sh/uv/concepts/tools/

3.11 工具

工具是提供命令行接口的 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 工具目录中创建虚拟环境。除非卸载该工具，否则该环境不会被移除。如果手动删除该环境，工具将无法运行。

重要

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

工具版本

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

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

1
2

$ uvx ruff@0.6.0 --version
ruff 0.6.0

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

1
2

$ uvx ruff --version
ruff 0.6.2

不过，如果 Ruff 发布了新版本，缓存未被刷新时不会使用它。

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

1
2

$ uvx ruff@latest --version
0.6.2

用 uv tool install 安装工具之后，uvx 默认会使用已安装的版本。

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

1

$ uv tool install ruff==0.5.0

ruff 与 uvx ruff 的版本相同：

1
2
3
4

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

不过，你可以通过显式请求最新版本来忽略已安装的版本，例如：

1
2

$ uvx ruff@latest --version
0.6.2

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

1
2

$ uvx --isolated ruff --version
0.6.2

uv tool install 同样遵循 {package}@{version} 和 {package}@latest 说明符，例如：

1
2

$ uv tool install ruff@latest
$ uv tool install ruff@0.6.0

升级工具

工具环境可以通过 uv tool upgrade 升级，也可以通过后续的 uv tool install 操作整体重建。

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

1

$ uv tool upgrade black

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

1

$ uv tool upgrade black --upgrade-package click

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

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

1

$ uv tool install black>=24

同样，工具升级会保留安装该工具时提供的设置。例如，uv tool install black --prerelease allow 之后再执行 uv tool upgrade black，会保留 --prerelease allow 设置。

注意

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

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

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

1

$ uv tool upgrade black --reinstall

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

1

$ uv tool upgrade black --reinstall-package click

包含额外依赖

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

1

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

在安装工具时也可以：

1

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

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

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

1

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

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

1

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

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

从额外包安装可执行文件

安装工具时，你可能希望把额外包的可执行文件包含进同一个工具环境。当你有一组相互配合的相关工具，或想安装多个共享依赖的可执行文件时，这很有用。

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

1

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

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

1

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

这会把 ansible、ansible-core 和 ansible-lint 包的所有可执行文件安装到同一个工具环境，使它们都能在 PATH 上使用。

--with-executables-from 选项可以与其他安装选项组合：

1

$ 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>）几乎等价于：

1

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

不过，使用 uv 的工具接口时有几处显著差异：

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

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