Skip to content

Interpreter Cleaner

The Interpreter Cleaner is a non-modal tool window that lists every Python interpreter registered in the IDE, shows its health status and logical and allocated sizes, and lets you remove broken or stale entries in bulk.

How to open: View → Tool Windows → Interpreter Cleaner.

What it shows

Each row in the table shows:

Column What it means
Status ✅ OK, ❌ Broken, or ⚠️ Unsupported
Name The interpreter name as it appears in IDE settings
Reason A one-line explanation of the status
Version Detected Python version (e.g. 3.11)
Env type How the environment was created (virtualenv, Poetry, Pipenv, Uv, Hatch, Conda, system, …)
Logical size Sum of file lengths in the environment directory; marked (partial) if some entries could not be read
Allocated size Filesystem-allocated space, when supported and available; not a prediction of reclaimable space
Path Path to the Python interpreter executable

The Broken only checkbox hides healthy interpreters so you can focus on entries that need attention. The Python version and Env type drop-downs narrow the list further.

Interpreters used by the current project or its modules have a tinted row and a bold name. Their registrations and environment directories are protected from purging.

Right-click a path to open its directory in the file manager or terminal.

Purging broken interpreters

Select one or more rows and click Purge selected to remove them from the IDE's interpreter registry. A confirmation bar appears before any changes are made — click Confirm purge to proceed or Cancel to abort.

Purging only removes the interpreter entry from the IDE's registry. It does not touch files on disk unless you also check Remove venv remnants (see below).

Only broken or unsupported interpreters can be purged. Healthy interpreters, and any interpreter used by the current project or one of its modules, are always skipped, even if they are broken.

The purge runs in the background, so the IDE stays responsive while large environments are removed. The purge buttons are disabled until it finishes.

Removing leftover venv directories

The Remove venv remnants option lets the Interpreter Cleaner delete the virtual environment directory from disk after it removes an interpreter entry from the registry. This is useful when you have broken or deleted-project interpreters that left behind orphaned .venv folders consuming disk space.

Which environments can be deleted

This option only applies to plain virtual environments — environments created directly with python -m venv, virtualenv, or similar tools, where the directory is owned entirely by that single project.

Managed environments are never deleted, even with "Remove venv remnants" enabled. This covers:

Tool Why it is protected
Poetry Poetry maintains its own registry of project→environment mappings in ~/.config/pypoetry/. Deleting the directory on disk would corrupt that registry without Poetry knowing, leaving poetry install in a broken state.
Pipenv Pipenv tracks environments by project path. Deleting the directory would desync Pipenv's bookkeeping, requiring a full pipenv --rm + pipenv install cycle to recover.
Uv Uv manages environments as part of a project workspace; removing the directory outside of uv itself can leave the workspace state inconsistent.
Hatch Hatch uses named environments per project, stored in a central location; deleting them externally breaks hatch env show and related commands.
Conda Conda maintains a global environments list (conda env list); deleting the directory without conda env remove leaves a dangling entry in that list.

In all cases the correct way to remove a managed environment is to use the tool that created it:

poetry env remove <env-name>
pipenv --rm
uv venv --clean   # or delete the .venv manually inside the project
hatch env remove <env-name>
conda env remove -n <env-name>

What "plain venv" means in practice

A virtual environment is treated as a plain venv — and is therefore eligible for physical deletion — when all of the following are true:

  1. The interpreter is not tagged as Pipenv, Poetry, Uv, Hatch, or Conda.
  2. The interpreter path resolves to a directory that contains a pyvenv.cfg file, or the directory is named .venv, venv, or env.

If those conditions are not met the directory is left on disk regardless of the "Remove venv remnants" setting.

Disk size for managed environments

The Logical size and Allocated size columns are computed in the background for local environments, including Poetry, Pipenv, Uv, Hatch, and Conda envs. Both columns sort by byte count rather than formatted text. Sizes are informational only — they do not affect whether an environment can be deleted.

Logical size sums file lengths. An incomplete scan is visibly marked (partial); hover over it for an explanation. Allocated size reports filesystem allocation where available, or — when unsupported or unavailable. Shared hardlinks and copy-on-write (CoW) data mean allocated size is not the space that deleting the environment would reclaim.

Allocated size uses the system du utility on macOS and Linux, following a symlinked environment root but not symlinks inside the environment, with hardlinks counted once per environment. It includes directory allocation and is reported at KiB granularity. Windows and systems without a usable du show —; logical size remains available. Symlinked package contents contribute to logical size but not to the environment's allocated size. Logical size follows links present in the tree; it does not discover all external base-Python dependencies or describe a self-contained runtime.

Note

Directory sizes are cached while filters change. Click Refresh to recalculate them. Size computation walks the directory tree. On large environments or slow disks it may take a moment to appear.