Skip to content

Introduction

docker-doctor is a static analysis tool for Dockerfile and Docker Compose files.

On this page

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 31 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.

Key features

25 built-in rules

Across five categories: Security, Performance, Best Practices, Compose, and Image Size.

0–100 health score

A human-readable label (Excellent, Good, Needs Work, Critical) so regressions are obvious at a glance.

Fix guidance for every diagnostic

Each finding carries a Help: line with the concrete fix, plus rules explain <rule> for more depth.

Fully configurable

Per-rule and per-category severities, plus file ignores, via docker-doctor.config.ts — or YAML/JSON with a published schema.

CI-friendly

Machine-readable --json output and a --score mode that exits non-zero below a health threshold.

Quick example

A scan of a small project with a misordered install:

npx @docker-doctor/cli@latest
  All 6 issues

  Security › 1 issue
  Performance › 2 issues
  Best Practices › 2 issues
  Compose › 0 issues
  Image Size › 1 issue

  Run docker-doctor --verbose to list every error and warning

    ":"     77 / 100 Good ✅
   .---.    ███████████████████████████████████████░░░░░░░░░░░
  ( ◠ ◠ )>  Docker Doctor (https://docker-doctor.vercel.app)
   \___/

Pass --verbose to list every diagnostic with its source lines, message, and fix:

⚠ WARN [docker-doctor/no-root-user]:1
>     1 │ FROM node:22-slim
      2 │ WORKDIR /app

  The container runs as root. Running as root allows potential container breakout vulnerabilities.
  Help: Add a non-root user (e.g., 'USER node' or 'USER 1000') to improve security.

API

docker-doctor also ships its scanning engine as a library:

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

Continue to Getting Started to run your first scan.