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 | | Compute Capability Check | Detect GPU architecture mismatches — catches why torch.cuda.is_available() returns False on new GPUs (e.g. Blackwell) even when driver and CUDA are healthy | | Python Version Compatibility | Detect Python version conflicts with AI libraries and dependency cascade impacts | | CUDA Auto-Installer | Execute CUDA Toolkit installation directly with --run; CI-friendly with --yes; preview with --dry-run | | Safe Install Commands | Get the exact pip install command that works with YOUR driver | | Extension Library Support | Install compilation packages (flash-attn, SageAttention, auto-gptq, apex, xformers) with CUDA version matching | | 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 | | MCP Server | Expose diagnostics to AI assistants (Claude Desktop, Zed) via Model Context Protocol | | CI/CD Ready | JSON output, proper exit codes, and CI-aware env-var persistence (GitHub Actions, GitLab CI, CircleCI, Azure Pipelines, Jenkins) |

Installation

pip install env-doctor

Or with uv (a faster Python package manager):

# Install as an isolated tool (won't touch your project env)
uv tool install env-doctor

# Or run once without installing
uvx env-doctor check

Both methods install the same package from PyPI — pick whichever you prefer.

MCP Server (AI Assistant Integration)

Env-Doctor includes a built-in Model Context Protocol (MCP) server that exposes diagnostic tools to

... View full README on GitHub