remove

Remove a virtual environment.

Aliases: rm, delete

Usage

scuv remove <name> [options]

Arguments

Options

Examples

scuv remove myproject           # Remove with confirmation
scuv remove myproject --force   # Remove without asking
scuv rm old-env -f              # Using alias

Project .venv Link

If the current directory has a .venv symlink to the environment being removed (made by scuv use <name> --link), remove deletes that link too, so uv and editors do not trip over a dangling .venv. A real .venv directory, or a link to anything else, is left alone. Under --json the removed link is reported as unlinked. If the link cannot be removed (for example, the directory is read-only), the environment is still removed, a warning is printed, and --json reports the reason as unlink_error.

Only the current directory is checked. If you remove the environment from somewhere else, scuv doctor in the project reports the dangling link and scuv doctor --fix removes it.

Check Before Removing

To see details about an environment before removing it:

# Show environment details (Python version, path, packages)
scuv info myproject
# Output (excerpt):
#   Name:       myproject
#   Python:     3.12
#   Path:       ~/.scuv/virtualenvs/myproject

Removing All Environments for a Python Version

To remove all environments that use a specific Python version:

# List environments to identify which use Python 3.12
scuv list
#   ml-env     3.11    ~/.scuv/virtualenvs/ml-env
#   myproject  3.12    ~/.scuv/virtualenvs/myproject
#   webapp     3.12    ~/.scuv/virtualenvs/webapp
#   system     3.13.1  /usr/bin/python3 (system)

# Remove each one
scuv remove myproject --force
scuv remove webapp --force

# Then optionally uninstall the Python version itself
scuv uninstall 3.12

See also: uninstall command for the complete workflow to uninstall a Python version and clean up associated environments.