Metadata-Version: 2.4
Name: find-venvs
Version: 0.2.0
Summary: Discover all Python virtual environments on your system
License-Expression: MIT
Project-URL: Repository, https://github.com/Akudavale/FIND_VENVS.git
Keywords: virtualenv,venv,conda,environment,discovery
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0
Dynamic: license-file

# find-venvs (`vf`)

Discover and manage **all** Python virtual environments on your system — regardless of name, tool, or location.

```
$ vf list
Found 7 virtual environment(s) under /home/abhishek

╭────┬──────────────────┬───────────────────────────────────────┬────────┬────────────────╮
│ Name             │ Path                                  │ Type   │ Python Version │
├────┼──────────────────┼───────────────────────────────────────┼────────┼────────────────┤
│ .venv            │ /home/abhishek/projects/api/.venv     │ venv   │ 3.11.4         │
│ groot            │ /home/abhishek/projects/web/groot     │ venv   │ 3.10.12        │
│ base             │ /home/abhishek/miniconda3/envs/base   │ conda  │ 3.9.7          │
╰────┴──────────────────┴───────────────────────────────────────┴────────┴────────────────╯
```

## Why `find-venvs`?

Every tool that creates virtual environments (`python -m venv`, `virtualenv`, `conda`, `poetry`, `pipenv`) only knows about the environments it created. There is no existing pip-installable tool that answers the simple question:

> **"Where are all the virtual environments on my machine?"**

`find-venvs` detects venvs by their **content** (`pyvenv.cfg` for standard venvs, `conda-meta/` for conda), not by name — so it finds `.venv`, `venv`, `env`, `groot`, or any arbitrary directory name.

## Installation

```bash
pip install find-venvs
```

Requires Python 3.8+. Works on Linux, macOS, and Windows.

> **Windows note:** The `--system` flag is not supported on Windows (no single filesystem root). Use `--root C:\` or `--root D:\` to scan a specific drive.

## Commands

### `vf list` — list all environments

```bash
vf list                        # scan home directory
vf list --root /some/dir       # scan a specific directory
vf list --system               # scan from filesystem root /
vf list --depth 4              # limit recursion depth (default: 8)
vf list --json                 # machine-readable JSON output
```

**JSON output example:**

```json
[
  {
    "name": ".venv",
    "path": "/home/abhishek/projects/api/.venv",
    "type": "venv",
    "python_version": "3.11.4"
  }
]
```

---

### `vf info <name>` — inspect a single environment

Shows disk size, installed package count, and last-modified time.

```bash
vf info .venv
vf info myenv --root /projects
```

```
╭─────────────────── .venv ───────────────────╮
│  Name          .venv                         │
│  Path          /home/abhishek/projects/.venv │
│  Type          venv                          │
│  Python        3.11.4                        │
│  Disk size     142.3 MB                      │
│  Packages      34                            │
│  Last modified 2024-11-20  14:32             │
╰──────────────────────────────────────────────╯
```

If multiple environments share the same name, `vf info` shows a numbered list and asks you to pick one.

---

### `vf clean` — find orphaned environments

Lists environments whose parent directory has no project files (`pyproject.toml`, `requirements.txt`, `.git`, `Makefile`, etc.) — a strong signal the project was deleted and the venv is leftover.

```bash
vf clean
vf clean --root /projects
```

---

### `vf del <name>` — delete an environment

```bash
vf del .venv                        # interactive confirmation
vf del .venv --yes                  # skip confirmation
vf del .venv --dry-run              # show what would be deleted, do nothing
vf del .venv --path /projects/api   # skip full scan, go directly to /projects/api/.venv
```

**Flags:**

| Flag | Short | Description |
|------|-------|-------------|
| `--yes` | `-y` | Skip the confirmation prompt |
| `--dry-run` | `-n` | Preview deletion without removing anything |
| `--path DIR` | `-p` | Parent directory of the venv — skips system scan |

When multiple environments share the same name and `--path` is not given, `vf del` shows a numbered picker so you choose exactly which one to remove.

---

## Global scan flags

All subcommands accept these flags:

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--root DIR` | `-r` | home directory | Root directory to scan |
| `--system` | | off | Scan from filesystem root `/` |
| `--depth N` | `-d` | 8 | Maximum recursion depth |

---

## Library API

You can use the scanner directly in your own scripts:

```python
from find_venvs import scan, VenvInfo
from pathlib import Path

for venv in scan(Path.home(), max_depth=6):
    print(venv.path, venv.venv_type, venv.python_version)
```

`scan()` yields `VenvInfo` dataclass instances:

```python
@dataclass
class VenvInfo:
    path: Path
    venv_type: str          # "venv" | "conda"
    python_version: str | None
```

---

## How detection works

| Signal | Detected as |
|--------|-------------|
| `pyvenv.cfg` present in directory | `venv` (works for `python -m venv`, `virtualenv`, `poetry`, `pipenv`) |
| `conda-meta/` directory present | `conda` |

Detection is purely content-based — the directory can have any name.

Directories known to never contain user venvs are skipped automatically: `node_modules`, `.git`, `__pycache__`, `/proc`, `/sys`, `/dev`, `.cache`, `snap`, and more. Symlinks are never followed.

---

## License

MIT
