2.3 使用工具

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

2.3 使用工具

许多 Python 包提供了可作为工具使用的应用。uv 对便捷地调用和安装工具提供了专门支持。

运行工具

uvx 命令可以在不安装工具的情况下调用它。

例如，运行 ruff：

1

$ uvx ruff

注意

这完全等价于：

1	$ uv tool run ruff

uvx 只是为方便而提供的别名。

参数可以放在工具名之后：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

$ uvx pycowsay hello from uv

  -------------
< hello from uv >
  -------------
   \   ^__^
    \  (oo)\_______
       (__)\       )\/\
           ||----w |
           ||     ||

使用 uvx 时，工具会被安装到临时的隔离环境中。

注意

如果你在项目中运行工具，而该工具需要先安装你的项目（例如使用 pytest 或 mypy 时），你应当使用 uv run 而不是 uvx。否则工具会在与你的项目隔离的虚拟环境中运行。

如果你的项目是扁平结构，例如模块没有放在 src 目录中，那么项目本身无需安装，使用 uvx 即可。在这种情况下，只有当你希望在项目依赖中固定该工具版本时，使用 uv run 才有额外好处。

包名与命令名不同的情况

调用 uvx ruff 时，uv 会安装提供 ruff 命令的 ruff 包。但有时包名与命令名并不相同。

--from 选项可用于从指定包调用命令，例如由 httpie 提供的 http：

1

$ uvx --from httpie http

请求指定版本

要以特定版本运行工具，请使用 command@<version>：

1

$ uvx ruff@0.3.0 check

要以最新版本运行工具，请使用 command@latest：

1

$ uvx ruff@latest check

如上所述，--from 选项也可以用来指定包版本：

1

$ uvx --from 'ruff==0.3.0' ruff check

或者约束到一个版本范围：

1

$ uvx --from 'ruff>0.2.0,<0.3.0' ruff check

注意 @ 语法只能用于精确版本。

请求附加组件

--from 选项可以用来运行带附加组件的工具：

1

$ uvx --from 'mypy[faster-cache,reports]' mypy --xml-report mypy_report

它也可以与版本选择组合使用：

1

$ uvx --from 'mypy[faster-cache,reports]==1.13.0' mypy --xml-report mypy_report

请求不同来源

--from 选项也可以用来从替代来源安装。

例如，从 git 拉取：

1

$ uvx --from git+https://github.com/httpie/cli httpie

你也可以从指定的命名分支拉取最新提交：

1

$ uvx --from git+https://github.com/httpie/cli@master httpie

或者拉取特定标签：

1

$ uvx --from git+https://github.com/httpie/cli@3.2.4 httpie

甚至可以拉取特定提交：

1

$ uvx --from git+https://github.com/httpie/cli@2843b87 httpie

或者使用 Git LFS 支持：

1

$ uvx --lfs --from git+https://github.com/astral-sh/lfs-cowsay lfs-cowsay

带插件的命令

可以包含额外的依赖，例如在运行 mkdocs 时包含 mkdocs-material：

1

$ uvx --with mkdocs-material mkdocs --help

安装工具

如果某个工具经常使用，把它安装到持久环境并加入 PATH 会比反复调用 uvx 更方便。

提示

uvx 是 uv tool run 的便捷别名。其他所有与工具交互的命令都需要完整的 uv tool 前缀。

安装 ruff：

1

$ uv tool install ruff

工具安装后，其可执行文件会被放入 PATH 中的 bin 目录，因此无需 uv 也能运行该工具。如果它不在 PATH 中，会显示警告，此时可以用 uv tool update-shell 把它加入 PATH。

安装 ruff 之后，它应该可以直接使用：

1

$ ruff --version

与 uv pip install 不同，安装工具不会让它的模块在当前环境中可用。例如，下面的命令会失败：

1

$ python -c "import ruff"

这种隔离对于减少工具、脚本和项目之间依赖的相互影响与冲突很重要。

与 uvx 不同，uv tool install 作用于包，会安装该工具提供的所有可执行文件。

例如，下面的命令会安装 http、https 和 httpie 可执行文件：

1

$ uv tool install httpie

此外，无需 --from 也可以包含包版本：

1

$ uv tool install 'httpie>0.1.0'

同样，也可以指定包来源：

1

$ uv tool install git+https://github.com/httpie/cli

或者带 Git LFS 的包来源：

1

$ uv tool install --lfs git+https://github.com/astral-sh/lfs-cowsay

与 uvx 一样，安装时也可以包含额外的包：

1

$ uv tool install mkdocs --with mkdocs-material

使用 --with-executables-from 标志，可以把多个相关的可执行文件安装到同一个工具环境中。例如，下面的命令会安装 ansible 的可执行文件，以及 ansible-core 和 ansible-lint 提供的可执行文件：

1

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

升级工具

要升级工具，请使用 uv tool upgrade：

1

$ uv tool upgrade ruff

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

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

1

$ uv tool install ruff>=0.4

如果要升级所有工具：

1

$ uv tool upgrade --all

请求 Python 版本

默认情况下，uv 在运行、安装或升级工具时会使用你的默认 Python 解释器（找到的第一个）。你可以用 --python 选项指定要使用的 Python 解释器。

例如，在运行工具时请求特定的 Python 版本：

1

$ uvx --python 3.10 ruff

或者在安装工具时：

1

$ uv tool install --python 3.10 ruff

或者在升级工具时：

1

$ uv tool upgrade --python 3.10 ruff

关于请求 Python 版本的更多细节，请参阅 Python 版本概念页面。

旧式 Windows 脚本

工具也支持运行旧式 setuptools 脚本。安装后，这些脚本可通过 $(uv tool dir)\<tool-name>\Scripts 访问。

目前只支持扩展名为 .ps1、.cmd 和 .bat 的旧式脚本。

例如，下面是运行命令提示符脚本的示例。

1

$ uv tool run --from nuitka==2.6.7 nuitka.cmd --version

此外，你无需指定扩展名。uvx 会自动按 .ps1、.cmd、.bat 的顺序为你查找相应文件。

1

$ uv tool run --from nuitka==2.6.7 nuitka --version

后续步骤

要进一步了解用 uv 管理工具，请参阅工具概念页面和命令参考。

或者继续阅读，了解如何处理项目。