astral-sh/uv

uv-tool

crates/uv-tool/ implements uv tool (and the uvx alias). It manages per-tool environments — each tool installed by uv lives in its own venv under the configured tool directory and ships a "receipt" describing how it was installed.

Purpose

uvx ruff should "just work": pick the right Python, build a tiny ephemeral environment with the right version of ruff, run it, and clean up. uv tool install ruff should make that environment persistent and put the ruff executable on PATH. This crate is the data layer behind both.

The design changed early in uv's history: a Jun 2024 PR (#4560) replaced a single shared tools.toml with per-tool receipt files (uv-receipt.toml) inside each tool environment. That model is still in use.

Directory layout

crates/uv-tool/src/
├── lib.rs           # Public API: ToolEnvironment, Error, find_executable_directory
├── tool.rs          # Tool struct: name, requirements, version, entry points
└── receipt.rs       # ToolReceipt: read/write uv-receipt.toml

Key abstractions

Type	File	Role
`ToolEnvironment`	`lib.rs`	A `PythonEnvironment` plus the `PackageName` of the primary tool, with helpers to look up its version and entry points.
`Tool`	`tool.rs`	The persisted record of an install: requirements, constraints, overrides, Python version, the resolved entry points.
`ToolEntrypoint`	`tool.rs`	A single console-script: name, target module, target attribute, executable path inside the venv.
`ToolReceipt`	`receipt.rs`	The on-disk `uv-receipt.toml` wrapper.
`Error`	`lib.rs`	Tool-related errors (broken environment, broken receipt, missing tool package, executable directory not found, …).

How it works

flowchart LR
    install["uv tool install ruff"] --> resolve[Resolve ruff + deps]
    resolve --> venv[Create per-tool venv<br/>uv-virtualenv]
    venv --> ipkg[Install resolved packages<br/>uv-installer]
    ipkg --> receipt[Write uv-receipt.toml<br/>ToolReceipt]
    receipt --> link[Link entrypoints into<br/>user_executable_directory]
    link --> shell[uv tool update-shell<br/>add dir to PATH]

    run["uv tool run / uvx ruff"] --> ephemeral[Resolve into temp env]
    ephemeral --> exec[Spawn entrypoint via uv run]

The tool directory

The directory is defined by uv-state (StateBucket::Tools) and printed by uv tool dir. Each tool gets a subdirectory named after the package, containing:

pyvenv.cfg and the rest of the venv layout.
uv-receipt.toml describing the install.
The installed packages under site-packages/.

Entry points and PATH

uv tool install reads each installed wheel's entry_points.txt to find console scripts, then links them from the tool's venv into a per-user executable directory (Linux: ~/.local/bin; macOS: ~/Library/Application Support/uv/tools/...; Windows: %LOCALAPPDATA%\uv\tools\...). uv tool update-shell is the cross-platform shim that adds that directory to the user's PATH by editing the right shell init file.

Upgrades

uv tool upgrade re-resolves a tool's requirements with --upgrade-package semantics, then re-installs into the same environment, preserving the receipt for any constraints the user added at install time.

`uvx`

uv tool run <name> (and the uvx alias) is implemented in crates/uv/src/commands/tool/run.rs and uses this crate to:

Look up the tool by name (or fall back to a "name == package == executable" assumption).
Resolve and install into a temporary env (cached in ~/.cache/uv/tools-vN/).
Spawn the executable.

Integration points

uv-python provides the base interpreter.
uv-virtualenv creates the env.
uv-installer + uv-resolver install the contents.
uv-install-wheel is consulted via read_record to enumerate entry points.
uv-state + uv-dirs decide where the tool dir lives.

Entry points for modification

Add a new field to the receipt — extend Tool and the serialization in tool.rs/receipt.rs. Keep backward-compatibility (existing receipts must still parse).
Change executable linking — find_executable_directory and the linking helpers in lib.rs. Note the platform-specific differences for Windows (where .exe shims need to be re-stamped via uv-trampoline-builder).
A new tool subcommand — implement in crates/uv/src/commands/tool/, calling into this crate's API.

Key source files

File	Purpose
`crates/uv-tool/src/lib.rs`	`ToolEnvironment`, errors, helper functions.
`crates/uv-tool/src/tool.rs`	`Tool` and `ToolEntrypoint`.
`crates/uv-tool/src/receipt.rs`	`ToolReceipt` (`uv-receipt.toml`).