Rules

Every rule docker-doctor ships, grouped by category.

On this page

docker-doctor ships 31 rules across 5 categories. Every diagnostic carries a full rule key (e.g. docker-doctor/no-root-user) that you can pass to rules explain or use to tune severity in your config. Each rule below links to a page with failing and fixed examples.

List everything docker-doctor knows about:

npx @docker-doctor/cli@latest rules list

Explain any single rule in depth:

npx @docker-doctor/cli@latest rules explain <rule>

Security

Catches Dockerfile patterns that widen your attack surface.

Rule	What it checks	Severity
`no-root-user`	Run the container as a non-root user	warning
`no-secrets-in-env`	Avoid storing secrets in ENV or ARG instructions	error
`pin-image-version`	Pin base images to a specific tag or digest	warning
`no-add-remote`	Avoid using ADD with remote URLs	warning

Performance

Reduces build time and layer bloat.

Rule	What it checks	Severity
`use-multi-stage`	Use multi-stage builds	info
`order-layers`	Order layers to maximize build cache utility	warning
`minimize-layers`	Minimize the number of image layers	info
`use-dockerignore`	Add a .dockerignore file	warning

Best Practices

Keeps Dockerfiles and Compose files clean and predictable.

Rule	What it checks	Severity
`require-healthcheck`	Add a HEALTHCHECK instruction	info
`prefer-copy-over-add`	Prefer COPY over ADD	warning
`use-exec-form`	Use exec form for CMD and ENTRYPOINT	warning
`require-labels`	Add LABEL metadata to images	info
`combine-apt-update-install`	Combine apt-get update and apt-get install	warning
`use-pipefail`	Use pipefail to catch pipeline command failures	warning
`absolute-workdir`	Use absolute paths for WORKDIR	warning
`avoid-run-cd`	Avoid changing directories with cd in RUN	info
`sort-multiline-args`	Sort multi-line arguments alphanumerically	info
`useradd-no-log-init`	Use --no-log-init with useradd	warning

Compose

Catches Docker Compose-specific misconfigurations.

Rule	What it checks	Severity
`no-version-key`	Remove the `version` key from the Compose file	warning
`require-resource-limits`	Define resource limits for services	warning
`require-restart-policy`	Set restart policy for services	warning
`use-depends-on-condition`	Use long-form depends_on with healthcheck conditions	info
`pin-service-image`	Pin service images to a specific tag or digest	warning
`no-privileged-service`	Do not run services in privileged mode	error
`no-docker-socket-mount`	Do not bind-mount the Docker socket into services	error
`no-plaintext-secrets`	Avoid literal secret values in Compose environment	warning
`undefined-model-reference`	Service model references must be declared in top-level models	error
`pin-model-version`	Pin models to a specific tag or digest	warning

Image Size

Keeps final images small.

Rule	What it checks	Severity
`prefer-slim-base`	Prefer slim, alpine, or distroless base images	info
`clean-package-cache`	Clean up package manager cache in the same RUN layer	warning
`avoid-dev-dependencies`	Avoid installing dev dependencies in the final stage	warning

See Configuration to change a rule's severity or turn off a whole category.