█  ▄ ▄ █ █ ▄▄▄▄  ▄   ▄              ____
█▄▀  ▄ █ █ █   █ █   █           .'`_ o `;__,
█ ▀▄ █ █ █ █▄▄▄▀  ▀▀▀█ .       .'.'` '---'  '
█  █ █ █ █ █     ▄   █  .`-...-'.'Reclaim disk space by cleaning unused Python environments.
           ▀      ▀▀▀    `-...-'

Star History

killpy

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

killpy discovers:

• .venv folders
• folders that contain pyvenv.cfg
• Poetry virtual environments
• Conda environments
• installed pipx packages
• __pycache__ directories

It shows sizes and lets you remove things explicitly from an interactive terminal UI.

Quickstart

Install:

pip install killpy

Run from current directory:

killpy

Scan a specific path:

killpy --path /path/to/project

Without installing:

pipx run killpy

or

uvx killpy

Why use killpy

• Fast discovery of Python environments with size metadata.
• Safer cleanup flow with explicit mark/delete actions.
• Works across tools (venv, pyvenv.cfg, Poetry, Conda, pipx).
• Includes cache cleanup via killpy clean or UI shortcut.

Interactive controls

• Ctrl+Q: close the app
• D: mark selected virtual environment for deletion
• Ctrl+D: delete marked virtual environments
• Shift+Delete: delete selected virtual environment immediately
• P: clean __pycache__ folders
• U: uninstall selected pipx package

CLI commands

Main app:

killpy

or

killpy --path /path/to/project

Cache cleanup command:

killpy clean

or

killpy clean --path /path/to/project

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 or pipx are not installed?

No. Missing tools are handled gracefully.

Can I scan outside the current folder?

Yes. Use killpy --path /target/path.

Does it auto-delete anything on startup?

No. Deletion requires explicit user action.

For AI assistants and contributors

• Project behavior and guardrails are documented in AGENTS.md.
• Useful local checks:

uv python -m compileall killpy
pre-commit run --all-files

Roadmap

• Delete __pycache__ folders
• Remove dist folders and build artifacts
• Clean installed package caches
• Delete .egg-info and .dist-info folders
• Analyze and remove unused dependencies

Contributing

Contributions are welcome.

1. Fork the repository
2. Create a branch: git checkout -b my-feature
3. Commit your changes: git commit -m 'Add my feature'
4. Push your branch: git push origin my-feature
5. Open a pull request

License

MIT. See LICENSE.

---

If killpy saved you time or disk space, consider starring the repo ⭐