venvkill 0.1.0

npkill for Python — Intelligent Environment Cleaner

venvkill 🐍💀

npkill for Python — Intelligent Python Environment Cleaner

venvkill is a powerful CLI tool that scans your system for Python virtual environments, analyzes them, scores them by deletion priority, and safely cleans them up — freeing gigabytes of disk space.

---

✨ Features

• 🔍 Smart Scanning — Detects venv, .venv, env, conda, poetry, and pipenv environments
• 📊 Metadata Analysis — Size, Python version, package count, last-used date
• 🧠 Scoring Engine — Ranks environments by deletion priority (size + age + broken status)
• 🎨 Rich UI — Color-coded, sortable, interactive terminal tables
• 🛡️ Safe Deletion — Move to trash first, then confirm permanent delete
• 📦 Cache Detection — pip cache, __pycache__, conda cache
• 📄 JSON Export — Export full report for scripting or CI pipelines
• ⚡ Auto-Clean — Batch delete environments unused beyond a threshold
• 🌐 Cross-Platform — Windows, macOS, Linux

---

📦 Installation

pip install venvkill

Or install from source:

git clone https://github.com/harshit/venvkill
cd venvkill
pip install -e .

---

🚀 Usage

Scan for environments

# Scan home directory
venvkill scan

# Scan a specific path
venvkill scan --path /projects

# Deep recursive scan
venvkill scan --deep

# Scan current directory (project mode)
venvkill scan --project

# Sort by size instead of score
venvkill scan --sort size

Example output:

╭──────────────────────────────────────────────────────────────────────────────────────────────────────╮
│                                      Python Environments                                             │
├────┬──────────┬────────┬──────────┬──────┬───────────┬───────┬────────┬──────────┬──────────────────┤
│ ID │ Name     │   Size │  Python  │ Pkgs │  Last Used │ Score │  Type  │  Status  │ Path             │
├────┼──────────┼────────┼──────────┼──────┼───────────┼───────┼────────┼──────────┼──────────────────┤
│  1 │ ml_env   │ 3.4 GB │  3.10.9  │  128 │  120d ago  │ 18.4  │  venv  │ INACTIVE │ /home/ml_env     │
│  2 │ .venv    │ 850 MB │  3.11.2  │   42 │   45d ago  │  4.0  │  venv  │  ACTIVE  │ /projects/.venv  │
│  3 │ old_proj │ 220 MB │ unknown  │    0 │  365d ago  │ 12.8  │  venv  │  BROKEN  │ /tmp/old_proj    │
╰────┴──────────┴────────┴──────────┴──────┴───────────┴───────┴────────┴──────────┴──────────────────╯

  Legend: ● Active  ● Inactive (>90d)  ● Broken

Interactively clean environments

# Interactive selection
venvkill clean

# Dry run (preview only)
venvkill clean --dry-run

# Permanently delete (skip trash)
venvkill clean --force

# Delete all found environments
venvkill clean --all

# Only show high-priority targets
venvkill clean --min-score 5.0

Detect and clean caches

# Show cache sizes
venvkill cache

# Also scan for __pycache__ in current dir
venvkill cache --path /projects

# Clean all detected caches
venvkill cache --clean

Auto-clean inactive environments

# Delete envs unused for > 180 days (default)
venvkill auto-clean

# Custom threshold
venvkill auto-clean --days 90

# Preview only
venvkill auto-clean --dry-run

Export results

venvkill export --output report.json

Manage trash

# List trashed environments
venvkill trash

# Permanently free trashed space
venvkill trash --empty

---

🧠 Scoring Formula

Environments are ranked by deletion priority:

score = (size_in_gb × 3) + (days_unused / 30) + (broken × 5)

Factor	Weight	Reason
Size (GB)	×3	Large envs free more disk space
Inactivity (months)	×1	Older = more likely abandoned
Broken environment	+5	No reason to keep a broken env

---

🎨 Color Coding

Color	Meaning
🟢 Green	Active (used within 90 days)
🟡 Yellow	Inactive (unused > 90 days)
🔴 Red	Broken (missing Python interpreter)

---

🛡️ Safe Deletion

By default, venvkill moves environments to a trash folder (/tmp/venvkill_trash/) rather than permanently deleting them. This gives you a safety net.

# See what's in trash
venvkill trash

# Permanently free the space
venvkill trash --empty

Use --force to skip trash and delete immediately.

---

📄 JSON Export

venvkill scan --json results.json

Output format:

[
  {
    "path": "/home/user/projects/ml_env",
    "type": "venv",
    "size_bytes": 3650000000,
    "size": "3.4 GB",
    "python_version": "3.10.9",
    "package_count": 128,
    "days_unused": 120,
    "broken": false,
    "inactive": true,
    "score": 18.4,
    "last_modified": "2024-10-01T12:00:00"
  }
]

---

🔧 Development

# Clone and set up
git clone https://github.com/harshit/venvkill
cd venvkill
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Build
python -m build

# Publish
twine upload dist/*

---

📋 Roadmap

• GUI version (Textual TUI)
• AI-powered recommendation engine
• Background monitoring daemon
• VSCode extension
• Usage analytics mode (opt-in)

---

📄 License

MIT © Harshit Singh

---

🤝 Contributing

PRs and issues welcome! Please open an issue before submitting large changes.