Skip to content
Back to search

env-doctor

Diagnose and Fix CUDA / GPU environments compatibility issues locally, in Docker, and CI/CD. CLI + MCP server available.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mitulgarg--env-doctor/badge.svg)](/listings/mitulgarg--env-doctor)

HTML

<a href="/listings/mitulgarg--env-doctor"><img src="/api/listings/mitulgarg--env-doctor/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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) | ✗ | ✅ |

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 520 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="https://raw.githubusercontent.com/mitulgarg/env-doctor/main/docs/assets/logo.svg" alt="Env-Doctor Logo" width="80" height="80">
  3. </p>
  4. <h1 align="center">Env-Doctor</h1>
  5. <p align="center">
  6. <strong>The missing link between your GPU and Python AI libraries</strong>
  7. </p>
  8. <p align="center">
  9. <a href="https://mitulgarg.github.io/env-doctor/">
  10. <img src="https://img.shields.io/badge/docs-github.io-blueviolet?style=flat-square" alt="Documentation">
  11. </a>
  12. <a href="https://pypi.org/project/env-doctor/">
  13. <img src="https://img.shields.io/pypi/v/env-doctor?style=flat-square&color=blue&label=PyPI" alt="PyPI">
  14. </a>
  15. <a href="https://pepy.tech/projects/env-doctor">
  16. <img src="https://static.pepy.tech/personalized-badge/env-doctor?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads" alt="PyPI Downloads">
  17. </a>
  18. <img src="https://img.shields.io/badge/python-3.10%2B-blue?style=flat-square" alt="Python">
  19. <a href="https://github.com/mitulgarg/env-doctor/blob/main/LICENSE">
  20. <img src="https://img.shields.io/github/license/mitulgarg/env-doctor?style=flat-square&color=green" alt="License">
  21. </a>
  22. <a href="https://github.com/mitulgarg/env-doctor/stargazers">
  23. <img src="https://img.shields.io/github/stars/mitulgarg/env-doctor?style=flat-square&color=yellow" alt="GitHub Stars">
  24. </a>
  25. <a href="https://discord.gg/5wDK6k8Fp">
  26. <img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Discord">
  27. </a>
  28. </p>
  29. ---
  30. > **"Why does my PyTorch crash with CUDA errors when I just installed it?"**
  31. >
  32. > Because your driver supports CUDA 11.8, but `pip install torch` gave you CUDA 12.4 wheels.
  33. **Env-Doctor diagnoses and fixes the #1 frustration in GPU computing:** mismatched CUDA versions between your NVIDIA driver, system toolkit, cuDNN, and Python libraries.
  34. It takes **5 seconds** to find out if your environment is broken - and exactly how to fix it.
  35. ## Doctor "Check" (Diagnosis)
  36. ![Env-Doctor Demo](https://raw.githubusercontent.com/mitulgarg/env-doctor/main/docs/assets/envdoctordemo.gif)
  37. ## Features
  38. | Feature | What It Does |
  39. |---------|--------------|
  40. | **One-Command Diagnosis** | Check compatibility: GPU Driver → CUDA Toolkit → cuDNN → PyTorch/TensorFlow/JAX |
  41. | **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 |
  42. | **Python Version Compatibility** | Detect Python version conflicts with AI libraries and dependency cascade impacts |
  43. | **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 |
  44. | **CUDA Auto-Installer** | Execute CUDA Toolkit installation directly with `--run`; CI-friendly with `--yes`; preview with `--dry-run` |
  45. | **Safe Install Commands** | Get the exact `pip install` command that works with YOUR driver |
  46. | **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 |
  47. | **Extension Library Support** | Install compilation packages (flash-attn, SageAttention, auto-gptq, apex, xformers) with CUDA version matching |
  48. | **AI Model Compatibility** | Check if LLMs, Diffusion, or Audio models fit on your GPU before downloading |
  49. | **WSL2 GPU Support** | Validate GPU forwarding, detect driver conflicts within WSL2 env for Windows users |
  50. | **Deep CUDA Analysis** | Find multiple installations, PATH issues, environment misconfigurations |
  51. | **Container Validation** | Catch GPU config errors in Dockerfiles before you build |
  52. | **MCP Server** | Expose diagnostics to AI assistants (Claude Desktop, Zed) via Model Context Protocol |
  53. | **CI/CD Ready** | JSON output, proper exit codes, and CI-aware env-var persistence (GitHub Actions, GitLab CI, CircleCI, Azure Pipelines, Jenkins) |
  54. | **Fleet Dashboard** *(optional)* | Web UI for monitoring multiple GPU machines — aggregate status, drill-down diagnostics, history timeline. Install with `pip install "env-doctor[dashboard]"` |
  55. ## Installation
  56. ### Core CLI
  57. The core CLI has no heavy dependencies — installs in seconds.
  58. ```bash
  59. pip install env-doctor
  60. ```
  61. ```bash
  62. # Or with uv (faster, isolated)
  63. uv tool install env-doctor
  64. uvx env-doctor check
  65. ```
  66. ### With Fleet Dashboard
  67. 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!
  68. ```bash
  69. pip install "env-doctor[dashboard]"
  70. ```
  71. This adds: `fastapi`, `uvicorn`, `sqlalchemy`, `aiosqlite`
  72. | | `pip install env-doctor` | `pip install "env-doctor[dashboard]"` |
  73. |---|---|---|
  74. | `env-doctor check` | ✅ | ✅ |
  75. | All CLI commands | ✅ | ✅ |
  76. | MCP server | ✅ | ✅ |
  77. | `env-doctor check --report-to` | ✅ | ✅ |
  78. | `env-doctor report install/status` | ✅ | ✅ |
  79. | `env-doctor dashboard` (web UI) | ✗ | ✅ |
  80. ## MCP Server (AI Assistant Integration)
  81. Env-Doctor includes a built-in [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that exposes 11 diagnostic tools to AI assistants like Claude Code and Claude Desktop.
  82. ### Quick Setup
  83. ```json
  84. // Claude Desktop config (~/.config/Claude/claude_desktop_config.json)
  85. {
  86. "mcpServers": {
  87. "env-doctor": {
  88. "command": "env-doctor-mcp"
  89. }
  90. }
  91. }
  92. ```
  93. <video src="https://github.com/user-attachments/assets/7e761c28-1f44-44a0-8dfd-cf06cb9939a2" autoplay loop muted playsinline width="100%"></video>
  94. Ask your AI assistant things like *"Check my GPU environment"*, *"Can I run Llama 3 70B on my GPU?"*, or *"Validate this Dockerfile for GPU issues"*.
  95. **Learn more:** [MCP Integration Guide](docs/guides/mcp-integration.md)
  96. ---
  97. ## Fleet Dashboard *(optional)*
  98. > The core CLI works standalone. The dashboard is an observability layer for teams running multiple GPU machines.
  99. <video src="https://github.com/user-attachments/assets/1ef99c91-3656-467b-9b0d-31fab6ec9797" autoplay loop muted playsinline width="100%"></video>
  100. `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.
  101. ### Quick Start
  102. **1. Start the dashboard** (any machine — no GPU needed):
  103. ```bash
  104. pip install "env-doctor[dashboard]"
  105. env-doctor dashboard
  106. # → Serving at http://localhost:8765
  107. # → Generated API token at ~/.env-doctor/api-token
  108. ```
  109. **2. Report from each GPU machine:**
  110. ```bash
  111. pip install env-doctor
  112. # One-time report
  113. env-doctor check --report-to http://<dashboard-host>:8765 --token <token>
  114. # Automatic reporting every 2 minutes (cron on Linux, Task Scheduler on Windows)
  115. env-doctor report install --url http://<dashboard-host>:8765 --token <token> --interval 2m
  116. ```
  117. ### What You Get
  118. - **Fleet overview** — sortable table with status, GPU, driver, CUDA, torch, and group filtering
  119. - **Topology view** — force-directed graph of all machines, colour-coded by health, grouped into clusters
  120. - **Activity log** — cross-fleet command log with status, output, and filtering
  121. - **Machine detail** — full diagnostics + snapshot history timeline
  122. - **Remote remediation** — queue `env-doctor` commands from the UI, executed on next check-in (no SSH needed)
  123. Smart change detection means stable machines only POST ~1 heartbeat every 30 minutes, not on every poll.
  124. **Learn more:** [Fleet Monitoring Guide](docs/guides/fleet-monitoring.md)
  125. ---
  126. ## Usage
  127. ### Diagnose Your Environment
  128. ```bash
  129. env-doctor check
  130. ```
  131. **Example output:**
  132. ```
  133. 🩺 ENV-DOCTOR DIAGNOSIS
  134. ============================================================
  135. 🖥️ Environment: Native Linux
  136. 🎮 GPU Driver
  137. ✅ NVIDIA Driver: 535.146.02
  138. └─ Max CUDA: 12.2
  139. 🔧 CUDA Toolkit
  140. ✅ System CUDA: 12.1.1
  141. 📦 Python Libraries
  142. ✅ torch 2.1.0+cu121
  143. ✅ All checks passed!
  144. ```
  145. **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:
  146. ```
  147. 🎯 COMPUTE CAPABILITY CHECK
  148. GPU: NVIDIA GeForce RTX 5070 (Compute 12.0, Blackwell, sm_120)
  149. PyTorch compiled for: sm_50, sm_60, sm_70, sm_80, sm_90, compute_90
  150. ❌ ARCHITECTURE MISMATCH: Your GPU needs sm_120 but PyTorch 2.5.1 doesn't include it.
  151. FIX: Install PyTorch nightly with sm_120 support:
  152. pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu126
  153. ```
  154. ### Notebook / Jupyter Output
  155. Inside a Jupyter, Colab, or VS Code notebook, the Python API renders a rich, self-contained HTML report inline:
  156. ```python
  157. from env_doctor import check
  158. check() # auto-renders HTML in notebooks, prints text in terminals
  159. ```
  160. Install the optional extra for notebook support: `pip install "env-doctor[notebook]"`.
  161. You can also force HTML from the CLI with `env-doctor check --format html > report.html`.
  162. ### Check Python Version Compatibility
  163. ```bash
  164. env-doctor python-compat
  165. ```
  166. ```
  167. 🐍 PYTHON VERSION COMPATIBILITY CHECK
  168. ============================================================
  169. Python Version: 3.13 (3.13.0)
  170. ❌ 2 compatibility issue(s) found:
  171. tensorflow: supports Python <=3.12, but you have Python 3.13
  172. torch: supports Python <=3.12, but you have Python 3.13
  173. ⚠️ Dependency Cascades:
  174. tensorflow [high]: propagates to keras, tensorboard
  175. torch [high]: propagates to torchvision, torchaudio, triton
  176. 💡 Consider using Python 3.12 or lower for full compatibility
  177. ============================================================
  178. ```
  179. ### Get Safe Install Command
  180. ```bash
  181. env-doctor install torch
  182. ```
  183. ```
  184. ⬇️ Run this command to install the SAFE version:
  185. ---------------------------------------------------
  186. pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118
  187. ---------------------------------------------------
  188. ```
  189. ### Install vLLM / SGLang Without Breaking CUDA
  190. ```bash
  191. env-doctor install vllm # or: env-doctor check --engine vllm
  192. ```
  193. ```
  194. ❌ 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.
  195. → Fix options (best first):
  196. 1. Install the CUDA 12.9 build of vLLM 0.30.0 — via CUDA minor-version compatibility
  197. 2. Upgrade the NVIDIA driver to ≥ 580 ... ⚠ RISKY
  198. 📋 Copy-to-fix: uv pip install vllm==0.30.0 --extra-index-url https://wheels.vllm.ai/0.30.0/cu129 --torch-backend=cu129
  199. ```
  200. 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`.
  201. ### Install CUDA Toolkit
  202. Display instructions or execute the installation directly:
  203. ```bash
  204. # Show platform-specific steps (default)
  205. env-doctor cuda-install
  206. # Preview what would run — no changes made
  207. env-doctor cuda-install --dry-run
  208. # Execute interactively (asks [y/N] before running)
  209. env-doctor cuda-install --run
  210. # Execute headlessly — great for CI/scripts
  211. env-doctor cuda-install --run --yes
  212. # Install a specific version, headless
  213. env-doctor cuda-install 12.6 --run --yes
  214. ```
  215. **Example dry-run output (Windows):**
  216. ```
  217. [DRY RUN] [1/1] winget install Nvidia.CUDA --version 12.2
  218. [DRY RUN] [1/1] nvcc --version
  219. CUDA 12.2 installation completed successfully.
  220. Verification: PASSED
  221. Full log: C:\Users\you\.env-doctor\install.log
  222. ```
  223. Every run writes a timestamped log to `~/.env-doctor/install.log` for debugging.
  224. **Supported Platforms:**
  225. - Ubuntu 20.04, 22.04, 24.04
  226. - Debian 11, 12
  227. - RHEL 8, 9 / Rocky Linux / AlmaLinux
  228. - Fedora 39+
  229. - WSL2 (Ubuntu)
  230. - Windows 10/11 (via `winget`)
  231. - Conda (all platforms)
  232. **Exit codes for CI pipelines:**
  233. | Code | Meaning |
  234. |------|---------|
  235. | `0` | Installation succeeded and verified |
  236. | `1` | An installation step failed |
  237. | `2` | Installed but `nvcc --version` failed |
  238. ### Install Compilation Packages (Extension Libraries)
  239. 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:
  240. ```bash
  241. env-doctor install flash-attn
  242. ```
  243. ```
  244. 🩺 PRESCRIPTION FOR: flash-attn
  245. ⚠️ CUDA VERSION MISMATCH DETECTED
  246. System nvcc: 12.1.1 | PyTorch CUDA: 12.4.1
  247. 🔧 Two options:
  248. 📦 OPTION 1: Downgrade PyTorch to match nvcc (12.1) — no system changes
  249. ⚙️ OPTION 2: Upgrade nvcc to match PyTorch (12.4) — better long-term
  250. (Full step-by-step commands shown for both options)
  251. ```
  252. ### Check Model Compatibility
  253. ```bash
  254. env-doctor model llama-3-8b
  255. ```
  256. ```
  257. 🤖 Checking: LLAMA-3-8B (8.0B params)
  258. 🖥️ Your Hardware: RTX 3090 (24GB)
  259. 💾 VRAM Requirements:
  260. ✅ FP16: 19.2GB - fits with 4.8GB free
  261. ✅ INT4: 4.8GB - fits with 19.2GB free
  262. ✅ This model WILL FIT on your GPU!
  263. ```
  264. List all models: `env-doctor model --list`
  265. **Cloud GPU Recommendations:**
  266. ```bash
  267. # Get cloud GPU recommendations for a model that doesn't fit
  268. env-doctor model llama-3-70b --recommend
  269. # Direct VRAM lookup (no model name needed)
  270. env-doctor model --vram 80000 --recommend
  271. ```
  272. ```
  273. ☁️ Cloud GPU Recommendations
  274. FP16 (~140.0 GB):
  275. $27.20 /hr azure ND96asr_v4 8x A100 (40GB each) 180.0GB free
  276. $29.39 /hr gcp a2-highgpu-8g 8x A100 (40GB each) 180.0GB free
  277. ...
  278. ```
  279. Automatic HuggingFace Support (New ✨)
  280. 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.
  281. ```bash
  282. # Fetches from HuggingFace on first run, cached afterward
  283. env-doctor model bert-base-uncased
  284. env-doctor model sentence-transformers/all-MiniLM-L6-v2
  285. ```
  286. **Output:**
  287. ```
  288. 🤖 Checking: BERT-BASE-UNCASED
  289. (Fetched from HuggingFace API - cached for future use)
  290. Parameters: 0.11B
  291. HuggingFace: bert-base-uncased
  292. 🖥️ Your Hardware:
  293. RTX 3090 (24GB VRAM)
  294. 💾 VRAM Requirements & Compatibility
  295. ✅ FP16: 264 MB - Fits easily!
  296. 💡 Recommendations:
  297. 1. Use fp16 for best quality on your GPU
  298. ```
  299. ### Validate Dockerfiles
  300. ```bash
  301. env-doctor dockerfile
  302. ```
  303. ```
  304. 🐳 DOCKERFILE VALIDATION
  305. ❌ Line 1: CPU-only base image: python:3.10
  306. Fix: FROM nvidia/cuda:12.1.0-runtime-ubuntu22.04
  307. ❌ Line 8: PyTorch missing --index-url
  308. Fix: pip install torch --index-url https://download.pytorch.org/whl/cu121
  309. ```
  310. ### More Commands
  311. | Command | Purpose |
  312. |---------|---------|
  313. | `env-doctor check` | Full environment diagnosis |
  314. | `env-doctor python-compat` | Check Python version compatibility with AI libraries |
  315. | `env-doctor cuda-install` | Step-by-step CUDA Toolkit installation guide |
  316. | `env-doctor install <lib>` | Safe install command for PyTorch/TensorFlow/JAX, inference engines (vLLM, SGLang), extension libraries (flash-attn, auto-gptq, apex, xformers, SageAttention, etc.) |
  317. | `env-doctor check --engine vllm[@ver]` | Check an inference engine against your driver before installing |
  318. | `env-doctor model <name>` | Check model VRAM requirements |
  319. | `env-doctor cuda-info` | Detailed CUDA toolkit analysis |
  320. | `env-doctor cudnn-info` | cuDNN library analysis |
  321. | `env-doctor dockerfile` | Validate Dockerfile |
  322. | `env-doctor docker-compose` | Validate docker-compose.yml |
  323. | `env-doctor init --github-actions` | Generate GitHub Actions workflow |
  324. | `env-doctor scan` | Scan for deprecated imports |
  325. | `env-doctor debug` | Verbose detector output |
  326. | `env-doctor dashboard` | Start fleet monitoring web UI *(requires `[dashboard]` extra)* |
  327. | `env-doctor report install` | Set up periodic reporting via cron (Linux) or Task Scheduler (Windows) |
  328. ### CI/CD Integration
  329. Generate a GitHub Actions workflow with one command:
  330. ```bash
  331. env-doctor init --github-actions
  332. ```
  333. This creates `.github/workflows/env-doctor.yml` — review, commit, and push. Your CI will validate the ML environment on every push and PR.
  334. Or add manually:
  335. ```bash
  336. # JSON output for scripting
  337. env-doctor check --json
  338. # CI mode with exit codes (0=pass, 1=warn, 2=error)
  339. env-doctor check --ci
  340. ```
  341. **Exit code semantics for `check --json` / `check --ci`:**
  342. | Code | Meaning |
  343. |------|---------|
  344. | `0` | All detected components are compatible (uninstalled libraries do not count as failures) |
  345. | `1` | Installed components have warnings or version conflicts |
  346. | `2` | One or more components are in an error state |
  347. **GitHub Actions example:**
  348. ```yaml
  349. - run: pip install env-doctor
  350. - run: env-doctor check --ci
  351. ```
  352. ## Documentation
  353. **Full documentation:** https://mitulgarg.github.io/env-doctor/
  354. - [Getting Started](docs/getting-started.md)
  355. - [Command Reference](docs/commands/check.md)
  356. - [MCP Integration Guide](docs/guides/mcp-integration.md)
  357. - [WSL2 GPU Guide](docs/guides/wsl2.md)
  358. - [CI/CD Integration](docs/guides/ci-cd.md)
  359. - [Architecture](docs/architecture.md)
  360. **Video Tutorial:** [Watch Demo on YouTube](https://youtu.be/mGAwxGuLpxk?si=Buf9yzNTSJmoirMU)
  361. ## Platform Support
  362. 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.
  363. **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.
  364. > macOS uses zsh, which treats `[]` as a glob pattern. Quote extras when installing: `pip install "env-doctor[dashboard]"`
  365. ## Contributing
  366. Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
  367. ## License
  368. MIT License - see [LICENSE](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.