uv Tool Commands: How to Run and Install Python CLI Tools

The uv tool subcommand provides uvx (or uv tool run) for ephemeral execution and uv tool install for permanent installation of Python CLI tools in isolated environments.

The uv package manager from astral-sh/uv includes a dedicated tool subcommand for managing Python-based command-line utilities. Whether you need to run a linter once or install a permanent development tool, the uv tool commands handle environment creation, dependency resolution, and executable placement automatically.

Understanding the uv Tool Subcommand

The uv tool functionality is implemented in the uv-tool crate, specifically within crates/uv-tool/src/tool.rs. This module defines the core commands for running, installing, and managing Python CLI tools. The system creates isolated virtual environments for each tool, ensuring dependencies do not conflict with your project environments or system Python.

Running Tools Without Installation

For one-off tasks, uv provides ephemeral tool execution that automatically cleans up after completion.

Using uvx for Ephemeral Execution

The uvx command serves as a convenient alias for uv tool run. It downloads the specified package into a temporary virtual environment, executes the requested command, and discards the environment immediately after.

# Run the Ruff linter without installing it

uvx ruff check .

# Equivalent explicit syntax

uv tool run ruff check .

Advanced uv tool run Options

When the package name differs from the executable name, or when you need specific versions or sources, use the --from flag:

# Run 'http' command from the 'httpie' package

uvx --from httpie http

# Run a specific version

uvx [email protected] check .

# Install with extras

uvx --from 'mypy[faster-cache,reports]' mypy --xml-report mypy_report

# Run from a Git repository

uvx --from git+https://github.com/httpie/cli@master http

Installing Tools Permanently

For tools you use regularly, uv tool install creates persistent environments and places executables in a dedicated bin directory.

Basic Tool Installation

Install a tool permanently using the package name. The command resolves dependencies and creates an isolated environment:

# Install Ruff permanently

uv tool install ruff

# Verify installation

ruff --version

Installing with Dependencies and Constraints

Specify version constraints, additional dependencies, or alternative sources during installation:

# Install with version constraint

uv tool install 'httpie>0.1.0'

# Install with extra dependencies

uv tool install mkdocs --with mkdocs-material

# Install from Git

uv tool install git+https://github.com/httpie/cli

# Install with Git LFS support

uv tool install --lfs git+https://github.com/astral-sh/lfs-cowsay

# Specify Python version for the tool environment

uv tool install --python 3.10 ruff

Managing Installed Tools

Once installed, tools require periodic updates and management.

Upgrading Tools

Use uv tool upgrade to update specific tools or all installed tools at once:

# Upgrade a specific tool

uv tool upgrade ruff

# Upgrade all installed tools

uv tool upgrade --all

Locating Tool Directories

The uv tool dir command reveals where tools and their executables are stored:

# Show the tool installation directory

uv tool dir

# Show only the bin directory (for PATH configuration)

uv tool dir --bin

Summary

• uvx (or uv tool run) executes Python CLI tools ephemerally without permanent installation, automatically cleaning up temporary environments.
• uv tool install creates persistent, isolated environments for tools and places executables in a dedicated bin directory for regular use.
• Advanced options include --from for package-to-executable mapping, version constraints, extras, Git sources, and --with for additional dependencies.
• Management commands uv tool upgrade and uv tool dir handle updates and environment location respectively.

Frequently Asked Questions

What is the difference between uvx and uv tool run?

uvx is a direct alias for uv tool run. Both commands execute Python packages in temporary, isolated environments that are discarded after execution. Use uvx for brevity when running tools ephemerally, or uv tool run when you prefer explicit, self-documenting syntax.

How do I install a specific version of a tool with uv?

Specify the version using standard Python package syntax during installation: uv tool install 'package==version' or uv tool install 'package>=version'. For example, uv tool install 'ruff==0.3.0' pins the exact version, while uv tool install 'httpie>0.1.0' sets a minimum version constraint.

Can I install tools from Git repositories using uv tool?

Yes, use the git+https:// or git+ssh:// URL scheme with uv tool install. For example: uv tool install git+https://github.com/httpie/cli. You can also specify branches, tags, or commits using @ syntax, and enable Git LFS support with the --lfs flag for repositories containing large files.

Where does uv store installed tools?

Installed tools are stored in a dedicated directory managed by uv, accessible via uv tool dir. Executables are placed in a bin subdirectory shown by uv tool dir --bin. Add this bin directory to your shell's PATH environment variable to invoke installed tools directly by name.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}