Tool execution

uv's tool model isolates each Python CLI tool (ruff, black, mypy, …) in its own venv with its own receipt. Two commands drive the model:

• uv tool install <name> — install once, get <name> on PATH forever.
• uvx <name> (uv tool run) — install transiently and run.

Layout

~/.local/share/uv/tools/<package>/
├── pyvenv.cfg
├── uv-receipt.toml         # Tool: requirements, version, entry points
├── bin/                    # Inside the venv
└── lib/python3.X/site-packages/

The receipt encodes what was asked for so future uv tool upgrade calls can re-resolve faithfully.

uv tool install ruff

flowchart LR
    cli[uv tool install ruff] --> resolve[Resolve ruff + deps]
    resolve --> py[Pick interpreter via uv-python]
    py --> venv[Create venv via uv-virtualenv]
    venv --> install[Install via uv-installer]
    install --> entry[Read entry_points.txt]
    entry --> receipt[Write uv-receipt.toml]
    receipt --> link[Link executables to user-bin]

The user-bin directory is determined by uv-tool::find_executable_directory. On Linux, it's typically ~/.local/bin. uv tool update-shell makes sure that directory is on PATH.

uvx ruff check .

flowchart LR
    cli[uvx ruff check .] --> cache_lookup{Tool cache hit?}
    cache_lookup -- yes --> exec
    cache_lookup -- no --> resolve[Resolve to a temp env]
    resolve --> install[Install]
    install --> exec[Spawn entrypoint]

The temp env is reused on subsequent calls — uv keys it by (tool, version, python) so the second uvx ruff run reuses the first run's environment.

Entry points & Windows

Console scripts on Windows need .exe shims. uv generates them from the trampolines in uv-trampoline-builder. The shims call back into the venv's python.exe with the right module/attribute, just like pip's do.

See also

• crates/uv-tool, crates/uv-installer, crates/uv-virtualenv.