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

Key features

21+ 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

npx @docker-doctor/cli@latest

✔ Scanned 4 files in 0.3s [~8 workers]

Dockerfile
  10:1  warning  Container should not run as root user  docker-doctor/no-root-user
  Help: Add a non-root user (e.g., 'USER node' or 'USER 1000') to improve security.

Score: 94 Good ✅

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.