uv tool uninstall

Uninstall one or more installed tools

uv tool uninstall

Uninstall one or more installed tools.

Usage

uv tool uninstall [OPTIONS] <NAME>...
uv tool uninstall --all

Description

Removes installed tools and their isolated environments. This command removes the tool’s virtual environment from the tools directory and unlinks the executables from the bin directory.

Multiple tools can be uninstalled in a single command by providing multiple tool names.

This action cannot be undone. The tool and its environment will be permanently removed.

Examples

Uninstall a single tool

uv tool uninstall ruff

Uninstall multiple tools

uv tool uninstall ruff black mypy

Uninstall all tools

uv tool uninstall --all

Uninstall with confirmation

# Using a shell prompt for confirmation
read -p "Are you sure you want to uninstall ruff? (y/n) " -n 1 -r
echo
if [[ $REPLY =~ ^[Yy]$ ]]; then
    uv tool uninstall ruff
fi

Arguments

NAME · string · required

The name of the tool(s) to uninstall. Multiple tool names can be provided separated by spaces.

uv tool uninstall ruff
uv tool uninstall ruff black mypy

The tool name is the package name, not the executable name. Use uv tool list to see installed tool names.

Options

--all · boolean

Uninstall all tools. This removes all installed tools and their environments.

uv tool uninstall --all

This will remove all installed tools. Use with caution.

What Gets Removed

When you uninstall a tool, uv removes:

1. Tool Environment: The isolated virtual environment in the tools directory
2. Executables: Symlinks/scripts from the bin directory
3. Metadata: Tool installation metadata and configuration

Example directory changes

Before uninstalling ruff:

~/.local/share/uv/tools/
  ├── ruff/
  └── black/

~/.local/bin/
  ├── ruff
  ├── black
  └── blackd

After uv tool uninstall ruff:

~/.local/share/uv/tools/
  └── black/

~/.local/bin/
  ├── black
  └── blackd

Behavior Details

Tool not found

If you try to uninstall a tool that isn’t installed, uv will report an error:

uv tool uninstall nonexistent-tool
# Error: Tool 'nonexistent-tool' is not installed

Partial failures

When uninstalling multiple tools, if some tools don’t exist, uv will:

• Uninstall the tools that do exist
• Report errors for tools that don’t exist
• Exit with a non-zero status code

uv tool uninstall ruff nonexistent black
# Uninstalls ruff and black, reports error for nonexistent

Dependencies

Uninstalling a tool removes only that tool and its dependencies. Other tools with shared dependencies are not affected (each tool has its own isolated environment).

Verifying Uninstallation

After uninstalling, verify the tool is removed:

# Check if tool is listed
uv tool list | grep ruff

# Try to run the command (should fail)
ruff --version
# Output: command not found: ruff

Uninstalling vs. Removing Cache

Uninstalling a tool removes the tool environment but doesn’t clear the package cache:

# Uninstall tool (removes environment, keeps cached packages)
uv tool uninstall ruff

# Reinstall is fast due to cache
uv tool install ruff

# To also clear the cache
uv cache clean ruff

Common Workflows

Remove and reinstall a tool

# Remove current installation
uv tool uninstall ruff

# Install specific version
uv tool install ruff==0.4.0

Clean up all development tools

# Uninstall development tools
uv tool uninstall black ruff mypy pytest

# Or uninstall everything
uv tool uninstall --all

Migrate to different version

# Old way: uninstall then install
uv tool uninstall ruff
uv tool install ruff==0.4.0

# Better way: use --force
uv tool install --force ruff==0.4.0

Use uv tool install --force to replace an existing installation without explicitly uninstalling first.

Troubleshooting

Tool still appears in PATH

After uninstalling, the executable might still be found if there are multiple installations:

# Check which command is being run
which ruff

# If it points to a different location, you may have another installation
# For example, via pip, pipx, or system package manager

Permission errors

If you encounter permission errors:

# Check tool directory permissions
ls -la $(uv tool dir)

# May need to fix ownership
# (Only if tools were installed by different user)

Executable still exists but doesn’t work

If the executable link remains but the tool doesn’t work:

# Manually remove the broken link
rm $(uv tool dir --bin)/ruff

# Then reinstall if needed
uv tool install ruff

Can’t uninstall due to locked environment

If a tool is actively running, uninstallation might fail:

# Stop any running instances of the tool
pkill -f ruff

# Then uninstall
uv tool uninstall ruff

Bulk Operations

Uninstall tools matching a pattern

# Uninstall all tools starting with 'py'
uv tool list | awk '{print $1}' | grep '^py' | xargs uv tool uninstall

Uninstall all but specific tools

# Keep ruff and black, remove others
uv tool list | awk '{print $1}' | grep -v '^ruff$\|^black$' | xargs uv tool uninstall

Backup tool list before uninstalling

# Save current tools
uv tool list > installed-tools.txt

# Uninstall all
uv tool uninstall --all

# Later, reinstall from backup
cat installed-tools.txt | awk '{print $1}' | xargs -n1 uv tool install

The backup approach installs the latest versions, not the original versions. Use uv tool list --show-version-specifiers for more precise backup.

Exit Codes

• 0: All specified tools were successfully uninstalled
• 1: One or more tools were not found or uninstallation failed
• 2: Invalid arguments or options provided

See Also

• uv tool install - Install a tool
• uv tool list - List installed tools
• uv tool run - Run a tool without installing it
• uv cache clean - Clean the package cache