pypurge

Find and delete Python artifacts (venvs, caches, build dirs) from your terminal. The Python equivalent of npkill for node_modules.

Heads up — name is provisional. I didn't realize there were already three other pypurge projects on GitHub when I started this. The name will likely change before any public release; for now it stays as pypurge while the project is finding its shape. Suggestions welcome.

Aviso — el nombre es provisional. No sabía que ya existían otros tres proyectos llamados pypurge en GitHub. Probablemente lo renombre antes de cualquier release público; por ahora se queda así mientras el proyecto se asienta. Sugerencias bienvenidas.

---

English | Español

---

English

What it does

pypurge scans a directory tree (and optional global cache locations) for Python artifacts that take up disk space — virtual environments, type-checker caches, test caches, coverage output, build leftovers — displays them in an interactive TUI, and lets you select which ones to delete.

Supported artifact types

Kind	Detected by
venv	pyvenv.cfg inside (PEP 405)
pycache	__pycache__/
mypy	.mypy_cache/
pytest	.pytest_cache/
ruff	.ruff_cache/
tox	.tox/
nox	.nox/
hypothesis	.hypothesis/
benchmarks	.benchmarks/
pyre	.pyre/
pytype	.pytype/
eggs	.eggs/
egg-info	*.egg-info/
htmlcov	htmlcov/
pip-cache	per-OS global pip cache
uv-cache	per-OS global uv cache
poetry-cache	per-OS global poetry cache
pdm-cache	per-OS global pdm cache

build/ and dist/ are intentionally excluded — those names are too ambiguous and may exist in non-Python projects.

Installation

Requires uv and Python 3.10+.

# Clone and run
git clone <repo-url> && cd pypurge
uv run pypurge

# Or install globally
uv tool install .

Usage

Note: global package-manager caches (pip/uv/poetry/pdm) are included by default regardless of -d. Use --no-globals to scan only the target directory.

# Scan current directory + global caches (all kinds by default)
pypurge

# Scan a specific directory
pypurge -d C:\dev

# Scan entire home directory
pypurge --full

# Sort by date instead of size
pypurge -s date

# Exclude directory names from the walk
pypurge --exclude vendor --exclude .tox

# Only specific artifact kinds
pypurge --types venv,pycache

# Skip specific kinds
pypurge --exclude-types pycache,htmlcov

# Skip global caches
pypurge --no-globals

# Preview without deleting
pypurge --dry-run

Keyboard shortcuts

Key	Action
Space	Toggle select/deselect current row
x	Delete all selected artifacts
r	Rescan directory
s	Cycle sort order (size / date / path)
j / Down	Move cursor down
k / Up	Move cursor up
q	Quit

CLI options

Option	Description	Default
-d, --directory	Directory to scan	. (current)
--full	Scan home directory	off
-s, --sort	Initial sort: size, date, path	size
--exclude	Directory names to skip during the walk (repeatable)	.git, node_modules, .hg, .svn
--types	Comma-separated artifact kinds to include (e.g. venv,pycache)	all
--exclude-types	Comma-separated artifact kinds to exclude	none
--no-globals	Skip global pip/uv/poetry/pdm caches	off
--dry-run	Show what would be deleted without deleting	off
--version	Show version
--help	Show help

How it works

1. Scan — Walks the directory tree using os.scandir (fast, non-blocking via asyncio.to_thread). Detects artifacts by directory name, suffix (.egg-info), or pyvenv.cfg (for venvs). Stops recursing inside detected artifacts.
2. Globals — Resolves per-OS paths for pip/uv/poetry/pdm caches (Windows LOCALAPPDATA/APPDATA, Linux XDG_CACHE_HOME, macOS ~/Library/Caches) and adds them up-front.
3. Display — Results stream into a Textual DataTable as they're found. Shows kind, path, size, Python version (for venvs), and last modified date.
4. Select — Mark artifacts for deletion with Space. The stats bar shows how many are selected and their total size.
5. Delete — Press x to delete all selected. Each row shows "Deleting..." during removal and disappears on success. The "Freed" counter updates in real time.

Safety

• Refuses to delete the currently active Python environment
• Refuses to delete anything inside system directories (C:\Windows, /usr, etc.)
• Venvs must contain pyvenv.cfg to be eligible
• Skips symlinks to avoid filesystem cycles
• Handles PermissionError gracefully (skips inaccessible dirs)
• --dry-run flag for safe previewing
• Selection step before deletion prevents accidental removes

Tech stack

• Textual — Terminal UI framework
• Click — CLI parsing
• uv — Package management
• hatchling — Build backend

---

Español

Qué hace

pypurge escanea un árbol de directorios (y opcionalmente ubicaciones de cache globales) para encontrar artifacts de Python que ocupan espacio — entornos virtuales, caches de type-checkers, caches de tests, output de coverage, restos de builds — los muestra en una TUI interactiva y te permite elegir cuáles eliminar.

Tipos de artifact soportados

Tipo	Detección
venv	pyvenv.cfg adentro (PEP 405)
pycache	__pycache__/
mypy	.mypy_cache/
pytest	.pytest_cache/
ruff	.ruff_cache/
tox	.tox/
nox	.nox/
hypothesis	.hypothesis/
benchmarks	.benchmarks/
pyre	.pyre/
pytype	.pytype/
eggs	.eggs/
egg-info	*.egg-info/
htmlcov	htmlcov/
pip-cache	cache global de pip (per-OS)
uv-cache	cache global de uv (per-OS)
poetry-cache	cache global de poetry (per-OS)
pdm-cache	cache global de pdm (per-OS)

build/ y dist/ quedaron deliberadamente afuera — son nombres demasiado ambiguos y pueden existir en proyectos no-Python.

Instalación

Requiere uv y Python 3.10+.

# Clonar y ejecutar
git clone <repo-url> && cd pypurge
uv run pypurge

# O instalar globalmente
uv tool install .

Uso

Nota: los caches globales (pip/uv/poetry/pdm) se incluyen por default sin importar -d. Usá --no-globals para escanear solo el directorio objetivo.

# Escanear directorio actual + caches globales (todos los tipos por default)
pypurge

# Escanear un directorio específico
pypurge -d C:\dev

# Escanear todo el home
pypurge --full

# Ordenar por fecha en vez de tamaño
pypurge -s date

# Excluir nombres de directorio del walk
pypurge --exclude vendor --exclude .tox

# Solo tipos específicos
pypurge --types venv,pycache

# Excluir tipos específicos
pypurge --exclude-types pycache,htmlcov

# Saltear caches globales
pypurge --no-globals

# Vista previa sin borrar
pypurge --dry-run

Atajos de teclado

Tecla	Acción
Space	Seleccionar/deseleccionar la fila actual
x	Eliminar todos los artifacts seleccionados
r	Re-escanear directorio
s	Cambiar orden (tamaño / fecha / ruta)
j / Abajo	Mover cursor abajo
k / Arriba	Mover cursor arriba
q	Salir

Opciones de CLI

Opción	Descripción	Default
-d, --directory	Directorio a escanear	. (actual)
--full	Escanear directorio home	desactivado
-s, --sort	Orden inicial: size, date, path	size
--exclude	Nombres de directorio a omitir en el walk (repetible)	.git, node_modules, .hg, .svn
--types	Lista CSV de tipos a incluir (ej: venv,pycache)	todos
--exclude-types	Lista CSV de tipos a excluir	ninguno
--no-globals	Saltear caches globales pip/uv/poetry/pdm	desactivado
--dry-run	Muestra qué se borraría sin borrar nada	desactivado
--version	Mostrar versión
--help	Mostrar ayuda

Seguridad

• Rechaza eliminar el entorno Python actualmente activo
• Rechaza eliminar cualquier path dentro de directorios del sistema (C:\Windows, /usr, etc.)
• Los venvs requieren pyvenv.cfg para ser elegibles
• Omite symlinks para evitar ciclos en el filesystem
• Maneja PermissionError silenciosamente (omite directorios inaccesibles)
• Flag --dry-run para vista previa segura
• Paso de selección antes de eliminar previene borrados accidentales