env-doctor

pip install env-doctor

# Or with uv (faster, isolated)
uv tool install env-doctor
uvx env-doctor check

pip install "env-doctor[dashboard]"

// Claude Desktop config (~/.config/Claude/claude_desktop_config.json)
{
  "mcpServers": {
    "env-doctor": {
      "command": "env-doctor-mcp"
    }
  }
}

pip install "env-doctor[dashboard]"
env-doctor dashboard
# → Serving at http://localhost:8765
# → Generated API token at ~/.env-doctor/api-token

pip install env-doctor

# One-time report
env-doctor check --report-to http://<dashboard-host>:8765 --token <token>

# Automatic reporting every 2 minutes (cron on Linux, Task Scheduler on Windows)
env-doctor report install --url http://<dashboard-host>:8765 --token <token> --interval 2m

env-doctor check

🩺 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!

🎯  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

from env_doctor import check
check()   # auto-renders HTML in notebooks, prints text in terminals

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
============================================================

env-doctor install torch

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

env-doctor install vllm             # or: env-doctor check --engine vllm

❌ 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

# 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

[DRY RUN] [1/1] winget install Nvidia.CUDA --version 12.2

[DRY RUN] [1/1] nvcc --version

CUDA 12.2 installation completed successfully.
Verification: PASSED

Full log: C:\Users\you\.env-doctor\install.log

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)

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!

# 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

☁️   Cloud GPU Recommendations

  FP16 (~140.0 GB):
    $27.20 /hr  azure  ND96asr_v4              8x A100 (40GB each)          180.0GB free
    $29.39 /hr  gcp    a2-highgpu-8g            8x A100 (40GB each)          180.0GB free
    ...

# Fetches from HuggingFace on first run, cached afterward
env-doctor model bert-base-uncased
env-doctor model sentence-transformers/all-MiniLM-L6-v2

🤖  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

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

env-doctor init --github-actions

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

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

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