env-doctor 0.1.1

A CLI tool to verify and fix AI/ML environment compatibility (Driver <-> CUDA <-> Wheels).

Env-Doctor

The missing link between your GPU and Python AI libraries

---

"Why does my PyTorch crash with CUDA errors when I just installed it?"

Because your driver supports CUDA 11.8, but pip install torch gave you CUDA 12.4 wheels.

Env-Doctor diagnoses and fixes the #1 frustration in GPU computing: mismatched CUDA versions between your NVIDIA driver, system toolkit, cuDNN, and Python libraries.

It takes 5 seconds to find out if your environment is broken - and exactly how to fix it.

Doctor "Check" (Diagnosis)

Features

Feature	What It Does
One-Command Diagnosis	Check compatibility: GPU Driver → CUDA Toolkit → cuDNN → PyTorch/TensorFlow/JAX
Safe Install Commands	Get the exact pip install command that works with YOUR driver
AI Model Compatibility	Check if LLMs, Diffusion, or Audio models fit on your GPU before downloading
WSL2 GPU Support	Validate GPU forwarding, detect driver conflicts within WSL2 env for Windows users
Deep CUDA Analysis	Find multiple installations, PATH issues, environment misconfigurations
Container Validation	Catch GPU config errors in Dockerfiles before you build
CI/CD Ready	JSON output and proper exit codes for automation

Installation

pip install env-doctor

Or from source:

git clone https://github.com/mitulgarg/env-doctor.git
cd env-doctor
pip install -e .

Usage

Diagnose Your Environment

env-doctor check

Example output:

🩺 ENV-DOCTOR DIAGNOSIS
============================================================

🖥️  Environment: Native Linux

🎮 GPU Driver
   ✅ NVIDIA Driver: 535.146.02
   └─ Max CUDA: 12.2

🔧 CUDA Toolkit
   ✅ System CUDA: 12.1.1

📦 Python Libraries
   ✅ torch 2.1.0+cu121

✅ All checks passed!

Get Safe Install Command

env-doctor install torch

⬇️ Run this command to install the SAFE version:
---------------------------------------------------
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118
---------------------------------------------------

Check Model Compatibility

env-doctor model llama-3-8b

🤖  Checking: LLAMA-3-8B (8.0B params)

🖥️   Your Hardware: RTX 3090 (24GB)

💾  VRAM Requirements:
  ✅  FP16: 19.2GB - fits with 4.8GB free
  ✅  INT4:  4.8GB - fits with 19.2GB free

✅  This model WILL FIT on your GPU!

List all models: env-doctor model --list

Validate Dockerfiles

env-doctor dockerfile

🐳  DOCKERFILE VALIDATION

❌  Line 1: CPU-only base image: python:3.10
    Fix: FROM nvidia/cuda:12.1.0-runtime-ubuntu22.04

❌  Line 8: PyTorch missing --index-url
    Fix: pip install torch --index-url https://download.pytorch.org/whl/cu121

More Commands

Command	Purpose
env-doctor check	Full environment diagnosis
env-doctor install <lib>	Safe install command for PyTorch/TensorFlow/JAX
env-doctor model <name>	Check model VRAM requirements
env-doctor cuda-info	Detailed CUDA toolkit analysis
env-doctor cudnn-info	cuDNN library analysis
env-doctor dockerfile	Validate Dockerfile
env-doctor docker-compose	Validate docker-compose.yml
env-doctor scan	Scan for deprecated imports
env-doctor debug	Verbose detector output

CI/CD Integration

# JSON output for scripting
env-doctor check --json

# CI mode with exit codes (0=pass, 1=warn, 2=error)
env-doctor check --ci

GitHub Actions example:

- run: pip install env-doctor
- run: env-doctor check --ci

Documentation

Full documentation: https://mitulgarg.github.io/env-doctor/

• Getting Started
• Command Reference
• WSL2 GPU Guide
• CI/CD Integration
• Architecture

Contributing

Contributions welcome! See CONTRIBUTING.md for details.

License

MIT License - see LICENSE