使用uvx运行和安装Python应用程序

许多 Python 包提供了可作为工具使用的应用程序。uv 使用uvx调用和安装这些工具。

uvx等价于uv tool run。

运行工具

uvx可以运行工具而不需要安装它。例如：

uvx ruff

在工具名称后面可以加参数。例如：

$ uvx pycowsay hello from uv

Installed 1 package in 3ms
~/.cache/uv/archive-v0/NFJJ3_C1qUMRjEyWHZVtN/lib/python3.12/site-packages/pycowsay/main.py:23: SyntaxWarning: invalid escape sequence '\ '
  """

  ------------
< hello world! >
  ------------
   \   ^__^
    \  (oo)\_______
       (__)\       )\/\
           ||----w |
           ||     ||

命令和包名不同的情况

调用 uvx ruff 时，uv 会安装 ruff 包，该包提供 ruff 命令。但有时包名和其提供的命令名并不一致。

这种情况下，可以使用 --from 选项从特定包中调用命令，例如，http 命令由 httpie 包提供，可这样调用：

uvx --from httpie http

指定特定的版本

使用以下命令运行工具的特定版本：

uvx ruff@0.3.0 check

运行工具的最新版本：

uvx ruff@latest check

--from选项也可以用来指定包的版本：

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

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

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

指定额外功能

--from 选项可用于运行带有额外功能的工具：

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

指定git分支：

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

指定标记：

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

带插件的命令

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

uvx --with mkdocs-material mkdocs --help

安装工具

对常用工具，最好安装到持久化环境中，并添加到PATH。

例如安装ruff:

uv tool install ruff

工具安装完成后，其可执行文件被放置到PATH的一个bin目录，之后运行tool就不再需要uv tool了。

如果该路径未被添加到 PATH 中，系统会显示警告信息，此时可使用uv tool update-shell命令将其添加到 PATH。

现在可以直接运行ruff：

ruff --version

需要注意的是，安装工具并不会使得它的模块在本虚拟环境中可用。例如执行以下命令会失败。

python -c "import ruff"

升级工具

要升级一个工具，运行uv tool upgrade：

uv tool upgrade ruff

工具升级会遵循安装工具时指定的版本约束。例如，先执行 uv tool install ruff >=0.3,<0.4 安装 Ruff，之后运行 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版本。

uvx --python 3.10 ruff

uv tool install --python 3.10 ruff

uv tool upgrade --python 3.10 ruff