跳到内容

使用工具

许多 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 选项来调用特定包中的命令，例如 httpie 包提供的 http 命令

$ 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

或者拉取特定的标签 (tag)

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

甚至是特定的提交

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

或者支持 Git LFS

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

带有插件的命令

可以包含额外的依赖项，例如在运行 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

或者带有 Git LFS 的包来源

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

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

$ uv tool install mkdocs --with mkdocs-material

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

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

升级工具

要升级工具，请使用 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 管理工具的更多信息，请参阅 工具概念页面和命令参考。

或者，继续阅读以了解如何进行项目开发。