<div align="center">

killpy

Reclaim disk space by finding and deleting Python environments you no longer use

</div>

---

The Problem

If you have been writing Python for more than a year, your disk is probably full of environments you forgot about.

Every project gets a .venv. Every tutorial leaves a Conda environment behind. Every poetry install creates a hidden virtualenv somewhere in ~/.cache. pyenv versions stack up. tox creates a .tox folder in every repo you ever tested. __pycache__ directories scatter everywhere. Build artifacts from old pip install -e . runs stay forever.

None of these get cleaned up automatically.

A typical developer machine accumulates 10-40 GB of Python environments over a few years — most of them abandoned and completely useless.

killpy scans your filesystem, shows you everything with its size, and lets you delete it — either from an interactive terminal UI or via a single command.

pip install killpy
killpy --path ~

---

What killpy detects

killpy supports 11 environment types across every major Python tool:

| Type | What is detected | Typical location | |------|-----------------|-----------------| | venv | .venv dirs and any folder containing pyvenv.cfg | project root | | poetry | Poetry virtual environments | ~/.cache/pypoetry/virtualenvs | | conda | Conda environments (conda env list) | ~/anaconda3/envs, ~/miniconda3/envs | | pipx | Installed pipx packages | ~/.local/share/pipx/venvs | | pyenv | pyenv-managed Python versions | ~/.pyenv/versions | | pipenv | Pipenv virtualenvs | ~/.local/share/virtualenvs | | hatch | Hatch environments | ~/.local/share/hatch/env | | uv | uv virtual environments | project root .uv/ | | tox | tox environments | .tox/ inside repo | | cache | __pycache__, .mypy_cache, .pytest_cache, .ruff_cache, global pip/uv caches | everywhere | | artifacts | dist/, build/, .egg-info, .dist-info | project root |

---

Quickstart

Install:

pip install killpy

Run the interactive TUI (scans current directory):

killpy

Scan your entire home folder to find everything:

killpy --path ~

No install required:

pipx run killpy
# or
uvx killpy

---

Interactive TUI

Launch the terminal UI to browse and delete environments visually:

killpy
killpy --path /path/to/scan

The TUI starts immediately and streams results as detectors finish. Select items, mark them for deletion, and confirm — nothing is deleted without explicit action.

Keyboard shortcuts

| Key | Action | |-----|--------| | Ctrl+Q | Quit | | D | Mark selected item for deletion | | Ctrl+D | Delete all marked items | | Shift+Delete | Delete selected item immediately | | P | Remove all __pycache__ folders | | U | Uninstall selected pipx package |

---

CLI reference

killpy list — inspect environments

killpy list                             # list all detected environments
killpy list --path ~/projects           # scan a specific path
killpy list --type venv --type conda    # filter by type (repeatable)
killpy list --older-than 90             # not accessed in the last 90 days
killpy list --json                      # machine-readable JSON output

killpy delete — remove environments

killpy delete                           # interactive confirmation before delete
killpy delete --yes                     # skip confirmation
killpy delete --dry-run                 # preview — nothing is deleted
killpy delete --type venv               # only a specific type
killpy delete --older-than 180 --yes    # delete stale envs, no prompt
killpy delete --path ~/projects

killpy stats — disk usage summary

killpy stats
killpy stats --path ~/projects
killpy stats --json

Example output:

         Environment stats
┌──────────────┬───────┬────────────┬──────────┐
│ Type         │ Count │ Total size │ Avg size │
├──────────────┼───────┼────────────┼──────────┤
│ venv         │    12 │    4.2 GB  │  350 MB  │
│ conda        │     3 │    2.1 GB  │  700 MB  │
│ cache        │    45 │  890.0 MB  │   20 MB  │
│ poetry       │     6 │  750.0 MB  │  125 MB  │
└──────────────┴───────┴────────────┴──────────┘

Total: 66 environment(s) — 7.9 GB

killpy clean — remove cache directories

killpy clean
killpy clean --path ~/projects

Removes __pycache__ directories recursively. Safe to use as a pre-commit hook.

---

killpy vs alternatives

| Tool | venv | conda | poetry | pipx | pyenv | caches | artifacts | TUI | CLI | |------|:----:|:-----:|:------:|:----:|:-----:|:------:|:---------:|:---:|:---:| | killpy | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | pyclean | ❌ | ❌ | ❌ | ❌ | ❌ | __pycache__ only | ❌ | ❌ | ✅ | | conda clean | ❌ | partial | ❌ | ❌ | ❌ | conda only | ❌ | ❌ | ✅ | | pip cache purge | ❌ | ❌ | ❌ | ❌ | ❌ | pip only | ❌ | ❌ | ✅ | | find . -name .venv -exec rm | venv only | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | manual |

No other single tool discovers, sizes, and removes environments across all major Python toolchains.

---

FAQ

My Mac/Linux disk is almost full — can killpy help?

Yes. Run killpy --path ~ to scan your home folder. The stats command gives an immediate breakdown of how many GB each env type is using. Most developers find 5-30 GB they can reclaim.

How do I delete all unused Python virtual environments at once?

killpy delete --type venv --older-than 90 --yes

This deletes every .venv / pyvenv.cfg env not accessed in the last 90 days, without prompting.

How do I find all .venv folders on my computer?

killpy list --type venv --path ~

Or for a quick JSON export:

killpy list --type venv --path ~ --json

How do I free up disk space used by Conda?

killpy list --type conda        # inspect
killpy delete --type conda      # delete selected

killpy runs conda env list internally and lets you delete individual environments. Alternatively, killpy --path ~ will surface them in the TUI.

How do I clean up Poetry virtualenvs?

Poetry stores virtualenvs in ~/.cache/pypoetry/virtualenvs. killpy detects and deletes them automatically — no manual path hunting required.

How do I remove all __pycache__ folders recursively?

killpy clean --path /path/to/project

Removes __pycache__ directories recursively under the target path.

Safety

killpy performs destructive actions (environment/package/cache deletion). Always review selected items before confirming removal. You are responsible for files deleted on your system.

Pre-commit hook

Use killpy clean before each commit to remove cache directories:

- repo: https://github.com/Tlaloc-Es/KillPy
  rev: 0.15.7
  hooks:
    - id: killpy
      pass_filenames: false

FAQ

Does it fail if Conda, pipx or pyenv are not installed?

Missing tools are handled gracefully — that detector is simply skipped. You get results for everything that is available.

Does it auto-delete anything?

Never. Deletion always requires an explicit action: a key press in the TUI, --yes on the CLI, or an interactive prompt. killpy is read-only on startup.

Can I preview what would be deleted without actually deleting?

killpy delete --dry-run

Nothing is removed. You see exactly what would happen.

Can I use it in CI or scripts?

Yes. killpy list --json is machine-readable. killpy delete --yes skips all prompts.

Can I combine filters?

Yes. For example:

killpy delete --type venv --older-than 90 --dry-run

Why is Python using so much disk space?

Each virtual environment is a full copy (or symlinked tree) of a Python interpreter plus all installed packages. A typical project .venv with common dependencies (Django, FastAPI, pandas, etc.) weighs 200 MB - 1 GB. Multiply by dozens of projects and you get tens of gigabytes — all orphaned when the project is archived.

---

Pre-commit hook

Keep your repo free of __pycache__ on every commit:

- repo: https://github.com/Tlaloc-Es/KillPy
  rev: 0.15.7
  hooks:
    - id: killpy
      pass_filenames: false

---

Safety

killpy performs destructive, irreversible actions. Always re