find-venvs 0.3.0

Discover all Python virtual environments on your system

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

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

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:

[
  {
    "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.

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.

vf clean
vf clean --root /projects

---

vf del <name> — delete an environment

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:

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:

@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