Getting Started
Install docker-doctor and run your first scan.
On this page
Install
docker-doctor is published as @docker-doctor/cli. There's nothing to install permanently — run it directly with npx or bunx:
npx @docker-doctor/cli@latestbunx @docker-doctor/cli@latestRun a scan
By default docker-doctor scans the current directory for Dockerfiles and Compose files:
npx @docker-doctor/cli@latest .You can point it at any directory:
npx @docker-doctor/cli@latest ./path/to/projectdocker-doctor searches that directory and its subdirectories for these file names. Letter case doesn't matter:
| Kind | File names |
|---|---|
| Dockerfile | Dockerfile, Dockerfile.* (such as Dockerfile.dev) and *.dockerfile |
| Compose | compose.yaml, docker-compose.yaml and variants such as compose.prod.yaml or docker-compose.override.yaml, with .yaml or .yml |
docker-doctor doesn't scan files with other names, such as Containerfile or Dockerfile-prod. When no file matches, it says so instead of printing a score.
Read the output
A scan prints how many issues it found per category, then the health score with its label. A scan of the packages/docker-doctor/test/fixtures/with-error fixture in the docker-doctor repository prints:
All 3 issues
Security › 1 issue
Performance › 0 issues
Best Practices › 2 issues
Compose › 0 issues
Image Size › 0 issues
Run docker-doctor --verbose to list every error and warning
84 / 100 Good ✅Add --verbose to see every finding with its file and line, a code frame, an explanation, and a Help: fix hint:
npx @docker-doctor/cli@latest . --verboseThe scan exits non-zero when any error-severity diagnostic is present, which makes it a natural CI gate — after your first scan, docker-doctor will offer to wire up a GitHub Actions workflow for you.
Next steps
- Browse every rule with
npx @docker-doctor/cli@latest rules list, or read the full list in Rules. - See all flags and exit codes in the CLI reference.
- Tune rule severities or ignore files in Configuration.
- Understand how the health score is calculated in Scoring.