envoic: A CLI to Find and Clean Python Virtual Environments

Source: Dev.to

Introduction

If you work across multiple Python projects, you’ve probably accumulated a graveyard of old .venv folders. Some are active, some are stale, and some are huge and silently eating disk space. envoic is a terminal‑first CLI that helps you find and clean these environments.

Features

• Scans directories to discover Python environments
• Detects venv, virtualenv, Conda, and optional plain .env directories
• Reports size, age, Python version, and stale status
• Supports safe cleanup workflows
• Compact, information‑dense output (inspired by TR‑200 style reporting)

Interactive management (envoic manage)

envoic manage ~/projects

• Checkbox selector
• Stale‑only preselection (--stale-only)
• Deep metadata mode (--deep)
• Explicit destructive confirmation (type "delete")

Non‑interactive cleanup (envoic clean)

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

# Delete stale envs (>90 days by default)
envoic clean ~/projects

# Custom threshold
envoic clean ~/projects --stale-days 180

• Irreversible deletions require typed confirmation unless --yes is used
• Supports --dry-run preview
• Validates selected paths stay inside the scan root
• Symlink‑safe deletion (removes the link, not the target)
• Per‑environment error handling (continues on failures)

Installation

No install needed (run via uvx):

uvx envoic scan .

Or install globally:

uv tool install envoic
# or
pipx install envoic

Commands Overview

envoic scan [PATH]          # Scan for environments
envoic list [PATH]          # List discovered environments
envoic info       # Show detailed info for a specific env
envoic manage [PATH]        # Interactive selection for removal
envoic clean [PATH]         # Non‑interactive stale cleanup
envoic version              # Show version

Platform Notes

• Windows: Best for Windows‑side environments.
• WSL: Best for Linux/WSL‑side environments; running envoic inside WSL is recommended for WSL projects.

Motivation

I wanted a single command that answers:

1. What Python environments do I actually have?
2. Which ones are stale?
3. How much space can I recover safely?

No spreadsheets, no manual searching, no guesswork.

Resources

• PyPI:
• GitHub:
• Documentation:

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