使用工具

许多 Python 包提供了可以作为工具使用的应用程序。 uv 具有专门的支持，可以轻松地调用和安装工具。

运行工具

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

例如，要运行 ruff

$ uvx ruff

注意

这完全等同于

$ uv tool run ruff

uvx 作为便利的别名提供。

可以在工具名称后提供参数

$ 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 选项从特定包中调用命令，例如，http 由 httpie 提供

$ uvx --from httpie http

请求特定版本

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

$ uvx [email protected] check

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

$ uvx ruff@latest check

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

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

或者，限制到一系列版本

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

请注意，@ 语法不能用于精确版本以外的任何内容。

请求 extras

可以使用 --from 选项来运行带有 extras 的工具

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

这也可以与版本选择结合使用

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

请求不同的来源

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

例如，从 git 中拉取

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

您还可以从特定的命名分支中拉取最新的提交

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

或拉取特定标签

$ uvx --from git+https://github.com/httpie/[email protected] httpie

甚至特定的提交

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

带有插件的命令

可以包括其他依赖项，例如，在运行 mkdocs 时包括 mkdocs-material

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

安装工具

如果经常使用某个工具，则将其安装到持久环境中并将其添加到 PATH 而不是重复调用 uvx 会很有用。

提示

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

要安装 ruff

$ uv tool install ruff

安装工具后，其可执行文件将放置在 PATH 中的 bin 目录中，这允许在没有 uv 的情况下运行该工具。如果它不在 PATH 上，则会显示警告，并且可以使用 uv tool update-shell 将其添加到 PATH。

安装 ruff 后，它应该是可用的

$ ruff --version

与 uv pip install 不同，安装工具不会使其模块在当前环境中可用。例如，以下命令将失败

$ python -c "import ruff"

这种隔离对于减少工具、脚本和项目的依赖项之间的交互和冲突非常重要。

与 uvx 不同，uv tool install 对包进行操作，并将安装该工具提供的所有可执行文件。

例如，以下命令将安装 http、https 和 httpie 可执行文件

$ uv tool install httpie

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

$ uv tool install 'httpie>0.1.0'

并且，类似地，对于包来源

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

与 uvx 一样，安装可以包括其他包

$ uv tool install mkdocs --with mkdocs-material

升级工具

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

$ uv tool upgrade ruff

工具升级将尊重安装工具时提供的版本约束。例如，uv tool install ruff >=0.3,<0.4 后跟 uv tool upgrade ruff 会将 Ruff 升级到范围 >=0.3,<0.4 中的最新版本。

要改为替换版本约束，请使用 uv tool install 重新安装该工具

$ uv tool install ruff>=0.4

要改为升级所有工具

$ uv tool upgrade --all

请求 Python 版本

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

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

$ uvx --python 3.10 ruff

或者，在安装工具时

$ uv tool install --python 3.10 ruff

或者，在升级工具时

$ uv tool upgrade --python 3.10 ruff

有关请求 Python 版本的更多详细信息，请参阅 Python 版本概念页面。

旧版 Windows 脚本

工具还支持运行旧版 setuptools 脚本。这些脚本在安装时可通过 $(uv tool dir)\<tool-name>\Scripts 获得。

目前仅支持具有 .ps1、.cmd 和 .bat 扩展名的旧版脚本。

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

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

此外，您不需要指定扩展名。 uvx 会自动查找以 .ps1、.cmd 和 .bat 结尾的文件，并按此顺序执行。

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

下一步

要了解有关使用 uv 管理工具的更多信息，请参阅工具概念页面和命令参考。

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