在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

astral-sh/uv

菜单

工具执行

相关源文件

此页面介绍了 uv 如何执行已安装为独立可执行文件的 Python 工具。它涵盖了通过 uv tool run 或 uvx 别名命令运行工具的过程。有关如何安装工具的信息，请参阅 工具安装。

概述

uv 中的工具执行使用户无需激活虚拟环境即可运行具有可执行入口点（如 black、ruff 或 pytest）的 Python 包。当用户通过 uv tool run 或 uvx 调用工具时，uv 会：

  1. 解析请求的工具及其依赖项
  2. 为工具创建或重用隔离环境
  3. 在该环境中执行工具的入口点

此方法允许在不污染全局 Python 环境的情况下隔离执行工具，同时通过标准命令行界面保持便捷访问。

命令调用

用户可以通过两种等效的接口执行工具

uv tool run <tool> [arguments...]  # Standard interface
uvx <tool> [arguments...]          # Convenient alias

这两种接口都接受额外的标志，例如 --with 以包含额外的包，--python 以指定 Python 解释器，以及 --constraints 以约束依赖项。

来源

工具请求处理

当用户执行工具命令时，uv 会将请求解析为结构化表示，然后再处理执行。

命令解析图

目标类型

ToolRequest 包含一个 Target，它有三种变体：

  1. 未指定：一个简单的包名，没有版本（例如 ruff）
  2. 版本：一个具有特定版本的包（例如 ruff@0.1.5）
  3. 最新：一个明确要求最新版本的包（例如 ruff@latest）

@version 语法提供了一种便捷的方式来请求特定版本的工具，而无需创建需求文件。

来源

环境解析

工具执行的一个关键部分是查找或创建适合运行工具的环境。此过程涉及检查现有环境、在需要时创建新环境以及解析依赖项。

环境解析图

环境解析过程遵循以下步骤：

  1. 确定请求是针对 Python 本身还是某个包
  2. 对于包，检查工具是否已安装且兼容
    • 如果指定了 --isolated，则始终创建一个新环境
    • 否则，尝试重用现有的已安装工具环境
  3. 如有必要，创建新环境
    • 解析依赖项（包括 --with、--constraints 等）
    • 通过查找兼容的解释器来处理 requires-python 约束
    • 将所有依赖项安装到环境中

uv 会在可能的情况下智能地重用环境以避免重复安装，但会在需要时创建隔离环境。

来源

工具执行过程

解析出环境后，uv 会处理工具的实际执行。

执行过程图

执行过程包括：

  1. 根据工具请求确定可执行文件名
  2. 构建运行可执行文件的命令
  3. 设置 PATH 环境变量以包含环境的脚本目录
  4. 生成进程并等待其完成
  5. 处理任何错误并向用户提供有用的输出

在执行工具时，uv 确保正确的 Python 环境处于活动状态，而不会修改用户的 shell，从而使其使用起来无缝且无侵入性。

来源

命令构建

对于像 black 这样的工具，执行过程是：

  1. 在工具的环境中查找可执行脚本
  2. 将环境的脚本目录添加到 PATH 前缀
  3. 生成运行可执行文件的进程
  4. 继承标准输入、输出和错误流

此方法允许工具像全局安装一样运行，而实际上使用的是 uv 维护的隔离 Python 环境。

辅助功能

uv 包含一些辅助功能以改进工具执行体验

可执行文件发现和提示

如果找不到请求的可执行文件，uv 会：

  1. 列出包提供的可用可执行文件
  2. 建议运行这些可执行文件的正确命令
  3. 检查可执行文件是否由依赖项提供，并建议改用该依赖项

这有助于用户快速找到正确的命令，而无需搜索文档。

$ uv tool run --from black whitespace
The executable `whitespace` was not found.
The following executables are provided by `black`:
- black
- blackd
Consider using `uv tool run --from black <EXECUTABLE_NAME>` instead.

来源

Python 版本细化

当工具具有特定的 Python 版本要求（requires-python）时，uv 会自动：

  1. 检测当前解释器是否不兼容
  2. 查找或下载兼容的 Python 版本
  3. 使用兼容的解释器重新创建环境
  4. 无缝地继续执行

这使得具有严格 Python 版本要求的工具能够无需手动干预即可运行。

来源

环境管理

工具执行利用两种环境：

缓存环境

对于使用 --isolated 或其他非标准配置运行的工具，uv 会创建内容寻址的缓存环境。

  1. 环境基于其需求和 Python 解释器进行哈希处理
  2. 相同的环境会在不同调用之间重复使用
  3. 这些环境存储在缓存目录中

已安装的工具环境

对于常用工具，uv 会维护持久环境

  1. 每个已安装的工具都有自己的专用环境
  2. 工具存储在用户级别的目录中
  3. 可执行文件链接到 PATH 上的目录

这种双重方法通过重用环境来平衡性能，通过隔离工具来保持隔离。

来源

工具收据系统

uv 使用收据系统来跟踪已安装的工具

收据系统跟踪：

  1. 工具的需求和约束
  2. 使用的 Python 解释器
  3. 所有已安装的可执行文件及其路径
  4. 安装选项

这些信息允许 uv 确定现有工具环境是否与新的执行请求兼容。

来源

与工具安装集成

工具执行与工具安装紧密合作

  1. 执行已安装的工具时，uv 会重用工具的环境
  2. 执行具有不同要求的工具时，uv 会创建一个临时环境
  3. 当工具未安装但需要频繁使用时，用户可以使用 uv tool install 将其永久安装。

这种集成在临时工具执行和永久工具安装之间创造了无缝的体验。

来源

结论

uv 中的工具执行提供了一种强大的方法，可以在不激活虚拟环境或手动管理依赖项的情况下运行 Python 工具。该系统智能地平衡了隔离性、性能和用户体验，使得 Python 工具对普通用户和高级用户来说都很容易使用。