Managing Tools in UV

Tool Interface Overview

• Tools are CLI-capable Python packages.
• Run tools on demand with uvx (alias for uv tool run).
• Install tools persistently with uv tool install.

Tool Execution (uvx)

• Executes the tool in a temporary, isolated environment.
• Cached for performance; deleted on uv cache clean.
• Example:

  uvx ruff --version
  uvx ruff@0.6.0 --version
  uvx ruff@latest --version

Tool Installation (uv tool install)

• Installs tool in a persistent virtual environment under the tools directory.
• Tool is available on your PATH if properly configured.
• Example:

  uv tool install ruff@0.5.0
  ruff --version
  uvx ruff --version  # Uses installed version by default

Tool Environments

• Temporary (uvx): Disposable, cacheable, removed on cache clean.
• Installed (uv tool install): Persistent, removed only on uninstall.

Tool Versions

• uvx and uv tool install support:
  • Specific version: tool@1.0.0
  • Latest: tool@latest
  • Default: latest available on first run
• Refresh cache by using @latest or --isolated.

Upgrading Tools

• Upgrade a tool:

  uv tool upgrade black

• Upgrade a specific package in a tool environment:

  uv tool upgrade black --upgrade-package click

• Reinstall during upgrade:

  uv tool upgrade black --reinstall

Including Additional Dependencies

• During execution:

  uvx --with coverage pytest

• During installation:

  uv tool install --with coverage pytest

Executables and bin Directory

• Executables from installed tools are symlinked (Unix) or copied (Windows) into:
  • Default: ~/.local/bin (or via $UV_TOOL_BIN_DIR, $XDG_BIN_HOME, etc.)
• Must be on the PATH to run from shell.

Add it using:

uv tool update-shell

Overwriting Existing Executables

• UV won’t overwrite executables not installed by UV.
• Use --force to override:

  uv tool install black --force

Relationship to uv run

Use uv run when the tool should interact with your project environment (e.g., pytest, mypy).