env-doctor

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 diagnostic tools to AI assistants like Claude Code and Claude Desktop.

Quick Setup for Claude Desktop

1. Install env-doctor:

   pip install env-doctor
   

2. Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

   {
     "mcpServers": {
       "env-doctor": {
         "command": "env-doctor-mcp"
       }
     }
   }
   

3. Restart Claude Desktop - the tools will be available automatically.

Available Tools (11 Total)

• env_check - Full GPU/CUDA environment diagnostics
• env_check_component - Check specific component (driver, CUDA, cuDNN, etc.)
• python_compat_check - Check Python version compatibility with installed AI libraries
• cuda_info - Detailed CUDA toolkit information
• cudnn_info - Detailed cuDNN library information
• cuda_install - Step-by-step CUDA installation instructions
• install_command - Get safe pip install commands for AI libraries
• model_check - Analyze if AI models fit on your GPU
• model_list - List all available models in database
• dockerfile_validate - Validate Dockerfiles for GPU issues
• docker_compose_validate - Validate docker-compose.yml for GPU configuration

Demo — Claude Code using env-doctor MCP tools

Example Usage

Ask your AI assistant:

• "Check my GPU environment"
• "Is my Python version compatible with my installed AI libraries?"
• "How do I install CUDA Toolkit on Ubuntu?"
• "Get me the pip install command for PyTorch"
• "Can I run Llama 3 70B on my GPU?"
• "Validate this Dockerfile for GPU issues"
• "What CUDA version does my PyTorch require?"
• "Show me detailed CUDA toolkit information"

Learn more: MCP Integration Guide

Fleet Dashboard (optional)

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.

How It Works

There are two roles — the dashboard host (receives and displays reports) and the GPU machines (run checks and send results). They communicate over a simple REST API.

  Dashboard Host                                GPU Machine 1
  ┌─────────────────────-┐                 ┌───────────────────────────────┐
  │ env-doctor dashboard │ ◄──── POST ──── │ env-doctor check --report-to  │
  │ (React UI + SQLite)  │    /api/report  │ (runs locally, POSTs result)  │
  └─────────────────────-┘                 └───────────────────────────────┘
         ▲                                     GPU Machine 2
         │                               ┌───────────────────────────────┐
         └──────────── POST ─────────────│ env-doctor check --report-to  │
                       /api/report       └───────────────────────────────┘

Step 1 — Start the dashboard on any machine with a reachable IP (a cheap CPU instance is enough, no GPU needed):

pip install "env-doctor[dashboard]"
env-doctor dashboard
# → Serving at http://localhost:8765

Step 2 — Report from each GPU machine (only needs the core CLI, not the [dashboard] extra):

pip install env-doctor

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

# Or: set up automatic reporting every 2 minutes
env-doctor report install --url http://<dashboard-host>:8765 --interval 2m

report install creates a scheduled task on the GPU machine — a cron job on Linux/macOS or a Windows Task Scheduler entry on Windows. That task runs env-doctor check --report-to <url> on the configured interval.

Smart Change Detection

The scheduled task fires every 2 minutes, but it does not POST every 2 minutes. Each run:

1. Runs env-doctor check locally on the GPU machine
2. Hashes the result (status, checks — excluding timestamps)
3. Compares to the last sent hash stored in ~/.env-doctor/report-state.json

| Condition | Action | |-----------|--------| | Hash changed (driver updated, library installed, new issue) | POST full report immediately | | Hash unchanged, 30 min since last POST | POST lightweight heartbeat (confirms machine is alive) | | Hash unchanged, heartbeat not due | Skip — no network call, sub-second no-op |

On a stable machine, this means ~1 POST every 30 minutes instead of 720.

Reporting Commands (run on GPU machines)

These commands run on each GPU machine, not on the dashboard host:

| Command | Where | What it does | |---------|-------|-------------| | env-doctor dashboard | Dashboard host | Starts the web UI and API server | | env-doctor check --report-to URL | GPU machine | Runs check locally, POSTs result to dashboard | | env-doctor report install --url URL | GPU machine | Creates a cron job / scheduled task on this machine | | env-doctor report status | GPU machine | Reads this machine's local config and last report time | | env-doctor report uninstall | GPU