Skip to main content

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us