DEV Community

Cover image for envoic: A CLI to Find and Clean Python Virtual Environments
Mahimai Raja J
Mahimai Raja J

Posted on

envoic: A CLI to Find and Clean Python Virtual Environments

#python #programming #devtools #productivity

If you work across multiple Python projects, you’ve probably accumulated a graveyard of old .venv folders.

Some are active.

Some are stale.

Some are huge and silently eating disk.

I built envoic to solve that.

What envoic does

envoic is a terminal-first CLI that:

  • scans directories to discover Python environments
  • detects venv, virtualenv, conda, and optional plain .env dirs
  • reports size, age, Python version, and stale status
  • now supports safe cleanup workflows

The output style is compact and information-dense, inspired by TR-200 style reporting.

Quick start

No install needed:

uvx envoic scan .
Enter fullscreen mode Exit fullscreen mode

Or install:

uv tool install envoic
# or
pipx install envoic
Enter fullscreen mode Exit fullscreen mode

Core commands 

envoic scan [PATH]
envoic list [PATH]
envoic info <ENV_PATH>
envoic manage [PATH]
envoic clean [PATH]
envoic version
Enter fullscreen mode Exit fullscreen mode

New in latest release: manage + clean

1) envoic manage (interactive)

Interactively pick environments to remove:

envoic manage ~/projects
Enter fullscreen mode Exit fullscreen mode

Features:

  • checkbox selector
  • stale-only preselection (--stale-only)
  • deep metadata mode (--deep)
  • explicit destructive confirmation (type "delete")

envoic manage sample

2) envoic clean (non-interactive stale cleanup)

Great for routine cleanup:

# preview first
envoic clean ~/projects --dry-run

# delete stale envs (>90d by default)
envoic clean ~/projects

# custom threshold
envoic clean ~/projects --stale-days 180
Enter fullscreen mode Exit fullscreen mode

envoic clean sample

Safety-first deletion design

Deleting environments is irreversible, so safety is the default:

  • requires typed confirmation (delete) unless --yes
  • supports --dry-run preview
  • validates selected paths stay inside scan root
  • symlink-safe deletion (remove link, not target)
  • per-env error handling (continues on failures)

Windows + WSL note

envoic scans from the environment where it runs.

  • Run in Windows → best for Windows-side envs
  • Run in WSL → best for Linux/WSL-side envs

For WSL projects, running envoic inside WSL is recommended.

Why I built it

I wanted one command that answers:

  • What Python environments do I actually have?
  • Which ones are stale?
  • How much space can I recover safely?

No spreadsheet, no manual find, no guesswork.

Links

If you try it, I’d love feedback and feature requests.

Top comments (0)