摘要：uv 提供了一个专门的接口用于与工具（tools）交互。工具可以通过 uv tool run 命令在未安装的情况下运行，此时其依赖项会被安装在一个与当前项目隔离的临时虚拟环境中。

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

工具（tools）是提供命令行界面的 Python 包。

uv 提供了一个专门的接口用于与工具（tools）交互。工具可以通过 uv tool run 命令在未安装的情况下运行，此时其依赖项会被安装在一个与当前项目隔离的临时虚拟环境中。

由于在未安装的情况下运行工具非常常见，因此提供了一个 uvx 别名等同于 uv tool run —— 这两个命令完全等价。为了简洁，文档中大多会使用 uvx 而不是 uv tool run。

uv tool run --help

Run a command provided by a Python package

Usage: uv tool run [OPTIONS] [COMMAND]

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

在工具名称后面可以提供参数：uvx pycowsay hello from uv

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

工具也可以通过 uv tool install 命令安装，此时其可执行文件会被添加到 系统路径 (PATH) 中 —— 虽然仍然使用隔离的虚拟环境，但该环境在命令执行完成后不会被删除。

uv tool install --help

Install commands provided by a Python package

Usage: uv tool install [OPTIONS]

Arguments:

The package to install commands from

在大多数情况下，使用 uvx 运行工具比安装工具更为合适。安装工具只有在需要让系统中的其他程序能够访问该工具时才有意义。

使用 uvx 运行工具时，虚拟环境会存储在 uv 缓存目录中，并被视为可丢弃的，即如果你运行 uv cache clean，该环境会被删除。环境仅被缓存是为了减少重复调用的开销。如果环境被删除，系统会自动重新创建一个新的环境。

uv cache --help

Manage uv's cache

Usage: uv cache [OPTIONS]

Commands:

clean Clear the cache, removing all entries or those linked to specific packages

prune Prune all unreachable objects from the cache

dir Show the cache directory

使用 uv tool install 安装工具时，虚拟环境会在 uv 工具目录中创建。除非工具被卸载，否则该环境不会被删除。如果手动删除了环境，工具将无法运行。

例如安装工具：uv tool install mcp-server-fetch

查询工具路径：whereis mcp-server-fetch

mcp-server-fetch: /Users/xxx/.local/bin/mcp-server-fetch

mcp-server-fetch -> /Users/xxx/.local/share/uv/tools/mcp-server-fetch/bin/mcp-server-fetch

默认情况下，uv 工具目录名为 tools，位于 uv 应用程序状态目录中，例如 ~/.local/share/uv/tools。可以通过环境变量 UV_TOOL_DIR 自定义该位置。

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

工具安装目录的路径：uv tool dir

/Users/xxx/.local/share/uv/tools

工具环境会被放置在一个与工具包同名的目录中，例如：.../tools/。

来源：架构笔记一点号