pyvdrift

Detect environment drift across all your Python projects.

Every Python developer with more than a handful of projects hits this: venvs scattered across your machine, requirements drifting from what's installed, broken interpreters, stale environments. pyvdrift is the cross-project health layer that sits on top of whatever tools you already use.

Install

pipx install pyvdrift

Quick Start

pyvdrift scan          # find all Python projects on your machine
pyvdrift check         # diff requirements vs actually installed packages
pyvdrift doctor        # diagnose broken venvs and interpreter mismatches
pyvdrift list          # show all known projects with health status
pyvdrift clean         # remove venvs not touched in N days
pyvdrift watch <path>  # monitor a project for drift in real time

Supported Package Managers

pyvdrift is tool-agnostic — it reads whatever format your project uses:

Tool	Detection	Lockfile
uv	uv.lock or [tool.uv]	uv.lock
Poetry	poetry.lock or [tool.poetry]	poetry.lock
Pipenv	Pipfile	Pipfile.lock
pip	requirements*.txt	—
Hatch	[tool.hatch]	—
PDM	pdm.lock or [tool.pdm]	pdm.lock
conda	environment.yml	—
setup.py/cfg	setup.py or setup.cfg	—

A single project can use multiple tools simultaneously — pyvdrift detects all of them.

Commands

pyvdrift scan [PATH] [--depth N] [--json] [--save]

Walk a directory tree and find all Python projects. Default path is ~, default depth is 5.

pyvdrift check [PATH] [--fix] [--json] [--include-dev]

Compare declared dependencies against what's actually installed in the project's venv. Shows missing packages, version mismatches, and undeclared packages.

pyvdrift doctor [PATH] [--json]

Run all health checks: venv exists, Python binary works, interpreter version matches, deps installed, lockfile in sync, tool available. Exit codes: 0 = ok, 1 = warnings, 2 = errors.

pyvdrift list [--depth N] [--sort-by health|name|tool|last-used] [--json]

Scan + doctor for every project in a compact dashboard.

pyvdrift clean [--dry-run] [--older-than DAYS] [--yes]

Find and remove stale venvs. Dry run by default — pass --no-dry-run --yes to actually delete.

pyvdrift watch <PATH> [--interval SECONDS]

Poll a project and re-check on change. Exit with Ctrl+C.

Design Principles

• Read-only by default — never mutates your projects unless you explicitly ask
• Pure Python — minimal dependencies, fast startup
• Tool-agnostic — works with whatever your project uses
• Cross-project — the health layer that no single tool provides
• stdlib-first — uses tomllib, configparser, ast, pathlib where possible

License

MIT