"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.
Diagnose and Fix CUDA / GPU environments compatibility issues locally, in Docker, and CI/CD. CLI + MCP server available.
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
Jupyter / Notebook Output
from env_doctor import check; check() renders a rich HTML diagnosis inline in Jupyter, Colab, or VS Code notebooks — falls back to text in the terminal
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
Inference Engine Resolver
Resolve vLLM / SGLang → torch → CUDA build → kernel libs against your driver; get the install command that actually runs instead of a default CUDA 13 wheel on a CUDA 12 box
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
Web UI for monitoring multiple GPU machines — aggregate status, drill-down diagnostics, history timeline. Install with pip install "env-doctor[dashboard]"
Installation
Core CLI
The core CLI has no heavy dependencies — installs in seconds.
pip install env-doctor
# Or with uv (faster, isolated)
uv tool install env-doctor
uvx env-doctor check
With Fleet Dashboard
If you want to manage a distributed system of multiple GPU nodes, this dashboard can help you from a observability POV. It adds a web UI for monitoring multiple GPU machines and has no effect on the core CLI. You will be able to soon take action directly from the dashboard via distributed env-doctor cli instances on each VM!
pip install "env-doctor[dashboard]"
This adds: fastapi, uvicorn, sqlalchemy, aiosqlite
pip install env-doctor
pip install "env-doctor[dashboard]"
env-doctor check
✅
✅
All CLI commands
✅
✅
MCP server
✅
✅
env-doctor check --report-to
✅
✅
env-doctor report install/status
✅
✅
env-doctor dashboard (web UI)
✗
✅
MCP Server (AI Assistant Integration)
Env-Doctor includes a built-in Model Context Protocol (MCP) server that exposes 11 diagnostic tools to AI assistants like Claude Code and Claude Desktop.
The core CLI works standalone. The dashboard is an observability layer for teams running multiple GPU machines.
pip install "env-doctor[dashboard]" unlocks a web UI that aggregates diagnostic results from every machine in your fleet into a single view — no SSH required.
Quick Start
1. Start the dashboard (any machine — no GPU needed):
pip install "env-doctor[dashboard]"
env-doctor dashboard
# → Serving at http://localhost:8765
# → Generated API token at ~/.env-doctor/api-token
🩺 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!
On new-generation GPUs (e.g. RTX 5070 / Blackwell), env-doctor catches compute capability mismatches — the reason torch.cuda.is_available() returns False even when your driver and CUDA are healthy:
🎯 COMPUTE CAPABILITY CHECK
GPU: NVIDIA GeForce RTX 5070 (Compute 12.0, Blackwell, sm_120)
PyTorch compiled for: sm_50, sm_60, sm_70, sm_80, sm_90, compute_90
❌ ARCHITECTURE MISMATCH: Your GPU needs sm_120 but PyTorch 2.5.1 doesn't include it.
FIX: Install PyTorch nightly with sm_120 support:
pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu126
Notebook / Jupyter Output
Inside a Jupyter, Colab, or VS Code notebook, the Python API renders a rich, self-contained HTML report inline:
from env_doctor import check
check() # auto-renders HTML in notebooks, prints text in terminals
Install the optional extra for notebook support: pip install "env-doctor[notebook]".
You can also force HTML from the CLI with env-doctor check --format html > report.html.
Check Python Version Compatibility
env-doctor python-compat
🐍 PYTHON VERSION COMPATIBILITY CHECK
============================================================
Python Version: 3.13 (3.13.0)
❌ 2 compatibility issue(s) found:
tensorflow: supports Python <=3.12, but you have Python 3.13
torch: supports Python <=3.12, but you have Python 3.13
⚠️ Dependency Cascades:
tensorflow [high]: propagates to keras, tensorboard
torch [high]: propagates to torchvision, torchaudio, triton
💡 Consider using Python 3.12 or lower for full compatibility
============================================================
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
---------------------------------------------------
❌ Default `pip install vllm==0.30.0` pulls a CUDA 13.0 build (torch 2.13.0), but the driver supports up to CUDA 12.6.
→ Fix options (best first):
1. Install the CUDA 12.9 build of vLLM 0.30.0 — via CUDA minor-version compatibility
2. Upgrade the NVIDIA driver to ≥ 580 ... ⚠ RISKY
📋 Copy-to-fix: uv pip install vllm==0.30.0 --extra-index-url https://wheels.vllm.ai/0.30.0/cu129 --torch-backend=cu129
Prefers a different CUDA build of the same version, then a different engine version, and only last a driver change. SGLang's sgl-kernel / FlashInfer / torch co-pins are resolved the same way. Installed engines are checked automatically by env-doctor check.
Install CUDA Toolkit
Display instructions or execute the installation directly:
# Show platform-specific steps (default)
env-doctor cuda-install
# Preview what would run — no changes made
env-doctor cuda-install --dry-run
# Execute interactively (asks [y/N] before running)
env-doctor cuda-install --run
# Execute headlessly — great for CI/scripts
env-doctor cuda-install --run --yes
# Install a specific version, headless
env-doctor cuda-install 12.6 --run --yes
For packages like flash-attn, SageAttention, auto-gptq, apex, and xformers that compile from source, env-doctor detects CUDA mismatches and provides two fix paths:
env-doctor install flash-attn
🩺 PRESCRIPTION FOR: flash-attn
⚠️ CUDA VERSION MISMATCH DETECTED
System nvcc: 12.1.1 | PyTorch CUDA: 12.4.1
🔧 Two options:
📦 OPTION 1: Downgrade PyTorch to match nvcc (12.1) — no system changes
⚙️ OPTION 2: Upgrade nvcc to match PyTorch (12.4) — better long-term
(Full step-by-step commands shown for both options)
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
Cloud GPU Recommendations:
# Get cloud GPU recommendations for a model that doesn't fit
env-doctor model llama-3-70b --recommend
# Direct VRAM lookup (no model name needed)
env-doctor model --vram 80000 --recommend
Automatic HuggingFace Support (New ✨)
If a model isn't found locally, env-doctor automatically checks the HuggingFace Hub, fetches its parameter metadata, and caches it locally for future runs — no manual setup required.
# Fetches from HuggingFace on first run, cached afterward
env-doctor model bert-base-uncased
env-doctor model sentence-transformers/all-MiniLM-L6-v2
Output:
🤖 Checking: BERT-BASE-UNCASED
(Fetched from HuggingFace API - cached for future use)
Parameters: 0.11B
HuggingFace: bert-base-uncased
🖥️ Your Hardware:
RTX 3090 (24GB VRAM)
💾 VRAM Requirements & Compatibility
✅ FP16: 264 MB - Fits easily!
💡 Recommendations:
1. Use fp16 for best quality on your GPU
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 python-compat
Check Python version compatibility with AI libraries
Env-Doctor is built for Linux and Windows — the platforms where NVIDIA GPUs and CUDA are available. All GPU diagnostics (driver, CUDA, cuDNN, library compatibility) target these platforms.
macOS is supported for non-GPU features: Fleet Dashboard hosting, model memory checks (env-doctor model), Python compatibility, project import scanning, and the MCP server. This makes a Mac a great centralised dashboard host while your Linux/Windows VMs handle the GPU workloads.
macOS uses zsh, which treats [] as a glob pattern. Quote extras when installing: pip install "env-doctor[dashboard]"
Pas encore de liste d'outils. Les serveurs distants en obtiennent une après le premier contrôle d'état.
FAQ
Questions
Comment installer Env Doctor ?
Copiez sur cette page la configuration stdio pour Cursor, Claude Desktop, Claude Code ou VS Code. Elle utilise l'installation de l'éditeur, pas un proxy PlugMCP.
Env Doctor nécessite-t-il une clé API ?
Aucune variable d'environnement requise n'est indiquée sur cette fiche.
Quel transport Env Doctor utilise-t-il ?
Env Doctor s'exécute en local via stdio.
Quand Env Doctor a-t-il été vérifié pour la dernière fois ?
Dernière vérification : 2026-10-26. Diagnose and Fix CUDA / GPU environments compatibility issues locally, in Docker, and CI/CD. CLI + MCP server available.