envscan 0.2.1

Scan directories to find Python virtual environments

envscan — CLI to discover Python environments

envscan is a small, open-source command-line tool that scans a directory tree and reports the Python environments it finds — venv, virtualenv, uv, and conda, plus pipenv/poetry and pyenv markers — in a clean, aligned table.

Install

pip install envscan

For local development (editable install from source):

python -m pip install -e .

Quick start

• Scan the current directory:

envscan

• Scan a specific directory and print JSON:

envscan --path ./project --format json

• Show each environment's Python version:

envscan --python-version

• List installed packages in each environment:

envscan --packages

• Search for a specific library across every environment found (optionally pinned to an exact version):

envscan --search "monai"
envscan --search "monai==1.2.7"

Command reference

• --path PATH : Path to scan (default .)
• --depth INT : Max recursion depth (default 3)
• --format {text,json} : Output format (default text)
• --include-hidden : Include hidden files and directories (.venv is always scanned regardless of this flag, since it's the standard name across venv/virtualenv/uv)
• --follow-symlinks : Follow symbolic links
• --python-version : Show each environment's Python version (runs its interpreter; failures are shown inline in the table, no --verbose needed)
• --packages : List installed packages in each environment (runs pip/conda/uv)
• --search QUERY : Only show environments with a given library installed, e.g. --search "monai" or --search "monai==1.2.7" (exact-version matching only — >=, <=, etc. are not supported)
• --json-file PATH : Write JSON output to the given file
• --verbose : Verbose output (extra diagnostic logging)

Notes

• By default envscan uses conservative file-marker heuristics (e.g., presence of pyvenv.cfg, conda-meta, Pipfile, .python-version) and does not execute any discovered interpreters. Use --python-version or --packages to opt into running an environment's own interpreter/pip/conda/uv.

Contributing

Contributions welcome — open a PR with tests.

License

MIT