uninstall
Remove an installed Python version.
Usage
scuv uninstall <version>
Arguments
| Argument | Required | Description |
|---|---|---|
version | Yes | Python version to remove |
Options
| Option | Description |
|---|---|
--cascade | Also remove all virtual environments using this Python version |
--force, -f | Skip confirmation for cascade removal (requires --cascade) |
--json | Output result as JSON |
Examples
scuv uninstall 3.12 # Remove Python 3.12
scuv uninstall 3.11.8 # Remove specific version
# Remove Python and all environments using it
scuv uninstall 3.12 --cascade
# Remove without confirmation prompt
scuv uninstall 3.12 --cascade --force
Uninstall a Python Version and All Associated Environments
Recommended workflow for a full cleanup:
# 1) Optional: preview which environments would be removed
scuv list --python-version 3.12
# 2) Remove Python 3.12 and all environments using it
scuv uninstall 3.12 --cascade
# 3) Verify cleanup
scuv list --pythons
scuv doctor
For non-interactive scripts, skip the confirmation prompt:
scuv uninstall 3.12 --cascade --force
If the target version is not installed, check available versions first:
scuv list --pythons
Cascade Removal
The --cascade flag also removes the virtual environments that lose their Python when it is uninstalled. This replaces the manual multi-step workflow.
Which environments count as using it is read from each environment’s
pyvenv.cfg (home), not from the version it records:
- An environment linked to an install being removed (
cpython-3.12.14-…) is removed. - An environment linked to uv’s minor-version link (
cpython-3.12-…, what current uv creates) is removed only if no other install of the same build is left to take that link over. With CPython 3.12.13 still installed,uninstall 3.12.14 --cascadekeeps it, and uv points it at 3.12.13. A remaining free-threaded 3.12 does not count: it is a different build with its own link. - A plain version removes the default builds only, as uv does: an
environment on a free-threaded install (
cpython-3.12.13+freethreaded-…) is not affected byuninstall 3.12.13. From uv 0.9.1, a version that names the patch leaves that patch’s pre-releases:uninstall 3.14.0does not take 3.14.0rc1, whileuninstall 3.14takes both. Older uv takes the pre-releases with the patch, and the cascade follows whichever uv is installed. - An environment on a Python uv does not manage (Homebrew, a
--python-pathinterpreter) is never removed. - An environment whose
pyvenv.cfgis missing, unreadable or has nohomeline is never removed either: which Python it uses cannot be told. It is named in a warning before anything is uninstalled (and inunverified_envsunder--json).
Environments are removed only after uv has run, and only those whose
interpreter is actually gone by then: if the uninstall fails before
removing anything, or uv kept a link alive, the environment is left in
place. If uv removed some installs and then failed, the environments
those served are still removed (not ones that were already broken before
uv ran), and the command reports uv’s error; under --json the error
envelope then carries the same data as below. Each
one is checked again just before removal: an environment replaced while
the Python was being uninstalled (another directory under the name, or
another home) is kept with a warning, and one that cannot be checked
(an I/O or permission error) is kept and counted as not removed. scuv
commands do not lock each other out yet, so avoid creating or removing
the same environment from another shell while a cascade runs. If one
environment cannot be removed, the others still are; it is reported with
a warning, and the command exits with status 1 although the Python is
gone.
--cascade takes plain version numbers only (3, 3.12, 3.12.14). A
request such as 3.13t, 3.12.0rc1 or cpython@3.12 is refused before
anything is removed, because its numbers alone do not say which installs
uv would remove.
scuv uninstall 3.12 --cascade
# • Found 2 environment(s) using Python 3.12:
# • - myproject
# • - webapp
# Remove these environments and uninstall Python 3.12? [y/N]
# • Uninstalling Python 3.12...
# • Removing 'myproject'...
# • Removing 'webapp'...
# • Removed 2 environment(s)
# ✓ Python 3.12 uninstalled
With --force, the confirmation prompt is skipped:
scuv uninstall 3.12 --cascade --force
With --json, the output includes the list of removed environments. When
any could not be removed, status is "error" (code
UNINSTALL_CASCADE_INCOMPLETE) and data adds failed_envs, with name
and error for each. Environments left alone because their interpreter
could not be read are listed in unverified_envs, with name and
reason:
scuv uninstall 3.12 --cascade --json
# {
# "status": "success",
# "command": "uninstall",
# "data": {
# "version": "3.12",
# "removed_envs": ["myproject", "webapp"]
# }
# }
Note: Without
--cascade, uninstalling a Python version does not remove virtual environments that were created with it. Those environments will become broken. Use--cascadeto handle this automatically, or follow the manual workflow below.
Manual Uninstall Workflow
If you prefer manual control (without --cascade):
Step 1: Identify affected environments
# List environments filtered by Python version
scuv list --python-version 3.12
# Output:
# myproject 3.12 ~/.scuv/virtualenvs/myproject
# webapp 3.12 ~/.scuv/virtualenvs/webapp
# Or use JSON for scripting
scuv list --json
Step 2: Handle affected environments
# Option A: Remove the environment entirely
scuv remove myproject --force
# Option B: Recreate with a different Python version
scuv remove myproject --force
scuv create myproject 3.13
# Option C: Keep it (will be broken until you reinstall that Python)
# Do nothing — scuv doctor can detect and help fix it later
Step 3: Uninstall the Python version
scuv uninstall 3.12
Step 4: Verify
# Confirm Python is removed
scuv list --pythons
# Check for broken environments
scuv doctor
# If any issues found:
scuv doctor --fix
Recovery
If you uninstalled a Python version without cleaning up environments first:
# Detect broken environments
scuv doctor -v
# Output (excerpt):
# ✗ broken virtualenv: 'myproject' is corrupted
# → scuv remove myproject && scuv create myproject <python-version>
# ✗ broken symlink: Python symlink in 'myproject' is broken
# → scuv remove myproject && scuv create myproject <python-version>
# Option 1: Reinstall the Python version
scuv install 3.12
scuv doctor --fix
# Option 2: Recreate affected environments with a new version
scuv remove myproject --force
scuv create myproject 3.13