uv 的工具管理系统支持在隔离的环境中安装、运行和管理基于 Python 的 CLI 工具（例如 pytest、black、ruff）。工具全局可访问，无需激活虚拟环境或修改系统 Python 安装。
工具管理系统包含两种主要操作模式
uv tool install 安装的工具存储在专用环境中，并在会话之间保持可用。uvx 或 uv tool run 运行的工具使用临时的缓存环境，这些环境可以根据需要共享或重新创建。来源
InstalledTools 结构体 crates/uv-tool/src/lib.rs57-61 管理用户系统中的持久化工具安装。它通过 ToolReceipt 文件处理工具目录布局、环境创建和元数据持久化。
ToolRequest 枚举 crates/uv/src/commands/tool/mod.rs18-52 将用户输入（例如 ruff@latest 或 python3.11）解析为结构化请求。Target 枚举处理版本规范和包解析。
来源
uv 提供了两种不同的工具工作流程
通过 uv tool install 安装的工具会创建由 InstalledTools 注册表管理的持久化环境 crates/uv/src/commands/tool/install.rs44-65 每个工具都得到
$UV_TOOL_DIR/<工具名称>/$XDG_BIN_HOME 或系统等效目录）uv-receipt.toml 中，用于升级/卸载操作通过 uvx 或 uv tool run 运行的工具使用 CachedEnvironment crates/uv/src/commands/project/environment.rs21-46 以进行临时执行
来源
工具执行系统（uv tool run 和 uvx）根据请求上下文使用不同的环境策略
get_or_create_environment() 函数 crates/uv/src/commands/tool/run.rs671-691 实现了这个逻辑，首先检查 InstalledTools::get_environment() 是否有兼容的持久化安装，然后回退到 CachedEnvironment 进行临时执行。
来源
工具存储在两个不同的位置进行管理
持久化工具存储（$UV_TOOL_DIR/）
$UV_TOOL_DIR/
├── .lock # Concurrent access protection
├── black/ # Tool-specific directory
│ ├── bin/python # Virtual environment
│ ├── lib/python3.x/ # Site packages
│ ├── pyvenv.cfg # Environment config
│ └── uv-receipt.toml # Tool metadata
└── ruff/
└── ...
可执行目录（tool_executable_dir()）
$XDG_BIN_HOME/ # Platform-specific bin directory
├── black -> /path/to/tool/black/bin/black
├── blackd -> /path/to/tool/black/bin/blackd
└── ruff -> /path/to/tool/ruff/bin/ruff
ToolReceipt 以 TOML 格式存储元数据 crates/uv-tool/src/receipt.rs19-42
Tool::to_toml() 方法 crates/uv-tool/src/tool.rs191-308 将此结构序列化为正确的格式。
来源
工具管理命令实现在 crates/uv/src/commands/tool/ 模块中
| 命令 | 实现 | 主要功能 |
|---|---|---|
uv tool install | install.rs44-65 | 使用 InstalledTools 进行持久化安装 |
uv tool run | run.rs82-106 | 通过 get_or_create_environment() 进行临时执行 |
uvx | run.rs64-68 | run uv tool 的别名，搭配 ToolRunCommand::Uvx |
uv tool list | list.rs17-24 | 通过 InstalledTools::tools() 枚举 |
uv tool uninstall | uninstall.rs16-51 | 通过 InstalledTools::remove_environment() 移除 |
The ToolRequest::parse() function crates/uv/src/commands/tool/mod.rs66-89 支持
ruff - 包的最新版本ruff@latest - 明确指定最新版本ruff@0.1.8 - 特定版本python3.11 - Python 解释器请求--from package executable - 从不同的包运行可执行文件来源
The entrypoint_paths() function crates/uv-tool/src/lib.rs398-441 通过读取包的 RECORD 文件并识别 scripts 目录中的脚本来发现工具可执行文件
The install_executables() function crates/uv/src/commands/tool/common.rs162-174 处理特定于平台的安装
replace_symlink() 创建符号链接 crates/uv/src/commands/tool/common.rs262The ExecutableProviderHints struct crates/uv/src/commands/tool/run.rs486-498 使用 matching_packages() crates/uv/src/commands/tool/common.rs33-52 来提供程序未找到的诊断消息，并建议替代方案。
来源
工具管理与 uv 的多个核心系统集成
Tool installation uses the same PubGrub resolver via resolve_environment() [crates/uv/src/commands/project/mod.rs] and resolve_names() for requirement resolution.
The refine_interpreter() function crates/uv/src/commands/tool/common.rs73-83 在工具需求与当前解释器冲突时，自动发现兼容的 Python 版本。
InstalledTools 管理的持久化工具将环境存储在 $UV_TOOL_DIR 中CachedEnvironment with content-addressed cachingCache parameterTool environments use the same installation pipeline
sync_environment() for package installationSitePackages for environment introspectionentrypoint_paths() for executable discovery来源
The tool management system uses a caching mechanism to avoid redundant work
Environments are content-addressed in the cache based on
系统会在创建新环境之前检查是否已存在具有完全相同要求的环境。
对工具的更新会修改现有环境，而不是创建新环境。
Tool executables are created differently depending on the platform
可执行文件被放置在用户 PATH 中的一个目录中，允许直接调用而无需激活环境。
来源
The tool management system interacts with several other components of uv
来源