Skip to main content

​
Synopsis

uv python uninstall [OPTIONS] <TARGETS>...
uv python uninstall [OPTIONS] --all

​
Description

Uninstall Python versions. Removes Python installations that were installed by uv. System Python installations cannot be uninstalled. Either specific Python versions must be provided, or use --all to uninstall all managed Python versions.

​
Arguments

​
<TARGETS>...

The Python version(s) to uninstall. See uv help python to view supported request formats. Required unless --all is specified. Examples:

​
Options

​
Installation Directory

​
-d, --install-dir <INSTALL_DIR>

The directory where the Python was installed.
  • Type: Path
  • Default: ~/.local/share/uv/python
  • Environment variable: UV_PYTHON_INSTALL_DIR

​
Uninstall All

​
--all

Uninstall all managed Python versions.
  • Conflicts with: <TARGETS>
Warning: This will remove all Python versions installed by uv.

​
Version Request Formats

The following Python version request formats are supported:
  • <version> e.g. 3, 3.12, 3.12.3
  • <version-specifier> e.g. >=3.12,<3.13
  • <version><short-variant> e.g., 3.13t, 3.12.0d
  • <version>+<variant> e.g., 3.13+freethreaded, 3.12.0+debug
  • <implementation> e.g. cpython or cp
  • <implementation>@<version> e.g. [email protected]
  • <implementation><version> e.g. cpython3.12 or cp312
  • <implementation><version-specifier> e.g. cpython>=3.12,<3.13
  • <implementation>-<version>-<os>-<arch>-<libc> e.g. cpython-3.12.3-macos-aarch64-none

​
Output Format

​
Successful Uninstall

uv python uninstall 3.12

Uninstalled Python 3.12.8
 - cpython-3.12.8-macos-aarch64-none

​
Multiple Versions

uv python uninstall 3.11 3.12

Uninstalled 2 versions
 - cpython-3.11.11-macos-aarch64-none
 - cpython-3.12.8-macos-aarch64-none

​
Version Not Found

uv python uninstall 3.15

error: Python 3.15 is not installed

Installed Python versions:
  cpython-3.13.1-macos-aarch64-none
  cpython-3.12.8-macos-aarch64-none
  cpython-3.11.11-macos-aarch64-none
  cpython-3.10.16-macos-aarch64-none

​
Uninstall All

uv python uninstall --all

Uninstalled 4 versions
 - cpython-3.13.1-macos-aarch64-none
 - cpython-3.12.8-macos-aarch64-none
 - cpython-3.11.11-macos-aarch64-none
 - cpython-3.10.16-macos-aarch64-none

​
No Managed Pythons

uv python uninstall --all

No managed Python versions found

​
Examples

​
Uninstall a specific version

uv python uninstall 3.12
Removes all Python 3.12.x installations.

​
Uninstall a specific patch version

uv python uninstall 3.12.4
Removes only Python 3.12.4.

​
Uninstall multiple versions

uv python uninstall 3.10 3.11
Removes Python 3.10.x and 3.11.x.

​
Uninstall PyPy

uv python uninstall [email protected]

​
Uninstall all managed Python versions

uv python uninstall --all
Warning: This removes all Python versions installed by uv.

​
Uninstall from custom directory

uv python uninstall 3.12 --install-dir /custom/python/dir

​
Uninstall specific full key

uv python uninstall cpython-3.12.8-macos-aarch64-none

​
Check before uninstalling

# List installed versions first
uv python list --only-installed

# Then uninstall
uv python uninstall 3.11

​
Use Cases

​
Free up disk space

# Check what's installed
uv python list --only-installed

# Remove old versions
uv python uninstall 3.9 3.10

​
Clean installation

# Remove all uv-managed Python
uv python uninstall --all

# Reinstall fresh
uv python install 3.12 3.13

​
Remove after upgrading

# Upgrade to latest patch
uv python install 3.12 --upgrade

# Old 3.12.7 is still there, remove it
uv python uninstall 3.12.7

​
Test environment cleanup

# After testing with multiple versions
uv python uninstall [email protected] 3.13t

​
Migration cleanup

# Migrated from 3.11 to 3.12
# Remove old version
uv python uninstall 3.11

​
Script cleanup

#!/bin/bash
# Clean up test Python installations

echo "Installed Python versions:"
uv python list --only-installed

read -p "Remove all managed Python versions? (y/n) " -n 1 -r
echo
if [[ $REPLY =~ ^[Yy]$ ]]; then
  uv python uninstall --all
  echo "All managed Python versions removed"
fi

​
Selective cleanup

# Keep 3.12 and 3.13, remove everything else
uv python list --only-installed | grep -v "3.12\|3.13" | while read -r version; do
  uv python uninstall "$version"
done

​
Verify and uninstall

# Check if specific version is installed
if uv python find 3.10 > /dev/null 2>&1; then
  echo "Uninstalling Python 3.10"
  uv python uninstall 3.10
else
  echo "Python 3.10 not installed"
fi

​
Reinstall

# Uninstall and reinstall to fix issues
uv python uninstall 3.12
uv python install 3.12

​
Important Notes

​
Virtual Environments

Warning: Uninstalling a Python version will break any virtual environments that use it. 
# Check what's using a Python version
find . -name "pyvenv.cfg" -exec grep -l "3.11" {} \;

# Recreate environments after uninstalling
uv sync  # In each project

​
System Python

uv cannot uninstall system Python installations. Only Python versions installed by uv can be removed. 
# This won't work if Python 3.11 is a system installation
uv python uninstall 3.11

# Error: Cannot uninstall system Python

​
Executables

Uninstalling a Python version also removes associated executables installed in the bin directory.

​
No Confirmation

The uninstall command does not ask for confirmation. Use carefully, especially with --all. 
# No "Are you sure?" prompt
uv python uninstall --all  # Immediately removes everything

​
Verification

​
After uninstalling

# Verify removal
uv python list --only-installed

# Check specific version is gone
uv python find 3.11  # Should fail if 3.11 was uninstalled

​
Check disk space freed

# Before
du -sh ~/.local/share/uv/python

# Uninstall
uv python uninstall 3.10 3.11

# After
du -sh ~/.local/share/uv/python

​
Troubleshooting

​
Cannot uninstall system Python

error: Cannot uninstall system Python installation
uv only uninstalls Python versions that it installed. System Python (from your OS package manager, Homebrew, etc.) cannot be removed by uv.

​
Version not found

error: Python 3.12 is not installed
The requested Python version is not installed, or it’s a system installation that uv doesn’t manage. Check installed versions: 
uv python list --only-installed

​
Virtual environment errors after uninstall

If you see errors in virtual environments after uninstalling Python: 
# Recreate the virtual environment
rm -rf .venv
uv sync

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us