uv tool list

List installed tools and their details

uv tool list

List installed tools and their details.

Aliases

• uv tool ls - Short alias for uv tool list

Usage

uv tool list [OPTIONS]
uv tool ls [OPTIONS]

Description

Displays information about tools installed with uv tool install. By default, shows the tool name and installed version. Additional information can be displayed using the various --show-* flags.

Examples

List all installed tools

uv tool list

Output:

ruff v0.3.0
black v24.2.0
mypy v1.8.0

Show tool installation paths

uv tool list --show-paths

Output:

ruff v0.3.0
  Path: /home/user/.local/share/uv/tools/ruff
  Executables:
    - /home/user/.local/bin/ruff
black v24.2.0
  Path: /home/user/.local/share/uv/tools/black
  Executables:
    - /home/user/.local/bin/black
    - /home/user/.local/bin/blackd

Show version specifiers

uv tool list --show-version-specifiers

Output:

ruff v0.3.0 (>=0.3.0,<0.4.0)
black v24.2.0 (==24.2.0)
mypy v1.8.0 (>=1.0.0)

Show additional dependencies

uv tool list --show-with

Output:

ruff v0.3.0
myapp v1.0.0
  With: pandas>=2.0.0, numpy>=1.24.0

Show all information

uv tool list --show-paths --show-version-specifiers --show-with --show-extras --show-python

List tools with Python version

uv tool list --show-python

Output:

ruff v0.3.0 (Python 3.12.1)
black v24.2.0 (Python 3.11.7)
mypy v1.8.0 (Python 3.12.1)

Options

--show-paths · boolean

Display the path to each tool environment and installed executable.

uv tool list --show-paths

--show-version-specifiers · boolean

Display the version specifier(s) used to install each tool.

uv tool list --show-version-specifiers

--show-with · boolean

Display the additional requirements installed with each tool (via --with flag during installation).

uv tool list --show-with

--show-extras · boolean

Display the extra requirements installed with each tool (via extras syntax like package[extra]).

uv tool list --show-extras

--show-python · boolean

Display the Python version associated with each tool.

uv tool list --show-python

Output Format

The default output shows tool names and versions:

tool-name v1.0.0
another-tool v2.5.1

With additional flags, more details are shown:

tool-name v1.0.0 (>=1.0.0,<2.0.0) (Python 3.12.1)
  Path: /home/user/.local/share/uv/tools/tool-name
  Executables:
    - /home/user/.local/bin/tool-name
    - /home/user/.local/bin/tool-name-extra
  With: dependency1>=1.0.0, dependency2>=2.0.0
  Extras: dev, test

Understanding Tool Information

Tool Path

The tool path shows where the isolated virtual environment for the tool is located. This is where the tool and its dependencies are installed.

Executables

The executables list shows all commands installed by the tool and where they’re linked. These are the commands you can run from your terminal.

Version Specifiers

Version specifiers show the constraints that were used when installing the tool. These constraints are preserved during upgrades.

With Dependencies

Shows additional packages that were installed alongside the tool using the --with flag.

Extras

Shows which optional features (extras) were installed with the tool.

Python Version

Displays which Python version is used in the tool’s isolated environment.

Filtering and Searching

Currently, uv tool list shows all installed tools. To check for a specific tool:

# Using grep
uv tool list | grep ruff

# Check if a tool is installed (returns exit code 0 if found)
uv tool list | grep -q ruff && echo "ruff is installed"

Troubleshooting

No tools listed

If no tools are shown, you haven’t installed any tools yet:

uv tool install ruff
uv tool list

Tool shows but command not found

The tool executable directory may not be on your PATH:

uv tool update-shell

Then restart your shell.

Unexpected tool versions

Verify the version specifier used during installation:

uv tool list --show-version-specifiers

To upgrade or change the version:

uv tool install --force "ruff==0.4.0"

Tool environment corruption

If a tool appears in the list but doesn’t work, try reinstalling:

uv tool uninstall tool-name
uv tool install tool-name

Machine-Readable Output

For scripting and automation, you can parse the output of uv tool list:

# Get list of tool names
uv tool list | awk '{print $1}'

# Get tool names and versions
uv tool list | awk '{print $1 " " $2}'

# Count installed tools
uv tool list | wc -l

Future versions of uv may add JSON output format for easier parsing.

See Also

• uv tool install - Install a new tool
• uv tool uninstall - Uninstall a tool
• uv tool run - Run a tool without installing it
• uv tool dir - Show the tools directory