Metadata-Version: 2.4
Name: envscan
Version: 0.2.1
Summary: Scan directories to find Python virtual environments
Author-email: Vamsee Yashwanth <vamsee.ny1@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/VamseeNY/envscan
Project-URL: Repository, https://github.com/VamseeNY/envscan
Project-URL: Documentation, https://github.com/VamseeNY/envscan#readme
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Dynamic: license-file

# 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.

![envscan output](docs/output.png)

Install
-------

```bash
pip install envscan
```

For local development (editable install from source):

```bash
python -m pip install -e .
```

Quick start
-----------

- Scan the current directory:

```bash
envscan
```

- Scan a specific directory and print JSON:

```bash
envscan --path ./project --format json
```

- Show each environment's Python version:

```bash
envscan --python-version
```

- List installed packages in each environment:

```bash
envscan --packages
```

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

```bash
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
