Your Dockerfiles are probably wrong. Docker Doctor finds out why.

Docker Doctor is an opinionated static analysis tool for Dockerfile and Docker Compose files. It scans your project, runs 21+ rules across security, performance, best practices, Compose, and image size — then gives you a health score and fix guidance.

Works with any project that uses Docker.

Website →

Install

1. Quick start

npx @docker-doctor/cli@latest

2. Install for agents

Once you have an audit, install the skill so your coding agent learns the /docker-doctor triage workflow and can fix the issues for you:

npx @docker-doctor/cli@latest install

Works with Claude Code, Cursor, Codex, OpenCode, and many more. After an interactive scan finds issues, Docker Doctor also offers to hand them straight to an agent detected on your machine.

Rules reference →

3. Run in CI

The GitHub Action (PunGrumpy/docker-doctor) scans every pull request and posts a sticky summary comment — advisory by default, with an opt-in gate. See the GitHub Actions guide for setup, inputs, and gating.

4. Configure

// docker-doctor.config.ts
import type { DockerDoctorConfig } from "@docker-doctor/cli";

export default {
  rules: {
    "docker-doctor/no-root-user": "error",
  },
} satisfies DockerDoctorConfig;

Prefer YAML? docker-doctor.config.yaml works too, with editor autocomplete via # yaml-language-server: $schema=https://docker-doctor.vercel.app/schema.json. A defineConfig helper is also exported for projects with @docker-doctor/cli installed — see the configuration docs.

How the score works

Every scan produces a 0-100 health score alongside a label (Excellent 🏆, Good ✅, Needs Work ⚠️, Critical 🚨).

Each diagnostic adds a penalty based on severity:

| Severity | Penalty | | --------- | ------- | | error | 10 | | warning | 4 | | info | 1 |

The penalties are summed, then the score is computed as an asymptotic decay curve rather than a simple subtraction:

score = round(100 * e^(-penalty / K))   // K = 70

A perfect project (no diagnostics) always scores exactly 100. As penalty increases, the score keeps decreasing — it approaches 0 but never gets stuck there, so the score stays meaningful (and can still register improvement) even on projects with a lot of findings. K = 70 was chosen so a single warning (penalty 4) still lands around 94 — comfortably inside the Excellent bucket — while errors and repeated warnings continue to meaningfully erode the score.

The label thresholds are unchanged: >= 90 Excellent, >= 75 Good, >= 50 Needs Work, otherwise Critical.

API

import { discoverProject, toJsonReport } from "@docker-doctor/cli";
import type { Diagnostic } from "@docker-doctor/cli";

Contributing

MIT and Issues welcome!