> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/astral-sh/uv/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
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

```bash theme={null}
uv tool list
```

Output:

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

### Show tool installation paths

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
uv tool list --show-paths --show-version-specifiers --show-with --show-extras --show-python
```

### List tools with Python version

```bash theme={null}
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

<ParamField path="--show-paths" type="boolean">
  Display the path to each tool environment and installed executable.

  ```bash theme={null}
  uv tool list --show-paths
  ```
</ParamField>

<ParamField path="--show-version-specifiers" type="boolean">
  Display the version specifier(s) used to install each tool.

  ```bash theme={null}
  uv tool list --show-version-specifiers
  ```
</ParamField>

<ParamField path="--show-with" type="boolean">
  Display the additional requirements installed with each tool (via `--with` flag during installation).

  ```bash theme={null}
  uv tool list --show-with
  ```
</ParamField>

<ParamField path="--show-extras" type="boolean">
  Display the extra requirements installed with each tool (via extras syntax like `package[extra]`).

  ```bash theme={null}
  uv tool list --show-extras
  ```
</ParamField>

<ParamField path="--show-python" type="boolean">
  Display the Python version associated with each tool.

  ```bash theme={null}
  uv tool list --show-python
  ```
</ParamField>

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

```bash theme={null}
# 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:

```bash theme={null}
uv tool install ruff
uv tool list
```

### Tool shows but command not found

The tool executable directory may not be on your `PATH`:

```bash theme={null}
uv tool update-shell
```

Then restart your shell.

### Unexpected tool versions

Verify the version specifier used during installation:

```bash theme={null}
uv tool list --show-version-specifiers
```

To upgrade or change the version:

```bash theme={null}
uv tool install --force "ruff==0.4.0"
```

### Tool environment corruption

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

```bash theme={null}
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`:

```bash theme={null}
# 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
```

<Note>
  Future versions of uv may add JSON output format for easier parsing.
</Note>

## See Also

* [uv tool install](/cli/tool-install) - Install a new tool
* [uv tool uninstall](/cli/tool-uninstall) - Uninstall a tool
* [uv tool run](/cli/tool-run) - Run a tool without installing it
* [uv tool dir](/cli/tool-dir) - Show the tools directory