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

> Learn to run and install Python CLI tools with uv tool commands. Discover how uvx enables ephemeral execution and uv tool install provides permanent installation in isolated environments.

- Repository: [Astral/uv](https://github.com/astral-sh/uv)
- Tags: how-to-guide
- Published: 2026-03-01

---

**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`](https://github.com/astral-sh/uv/blob/main/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.

```bash

# 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:

```bash

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

uvx --from httpie http

# Run a specific version

uvx ruff@0.3.0 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:

```bash

# 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:

```bash

# 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:

```bash

# 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:

```bash

# 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.