Dockerfile Optimization Best Practices

Comprehensive Dockerfile optimization guide sourced exclusively from official Docker documentation. Contains 48 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• Writing new Dockerfiles or modifying existing ones

• Optimizing Docker build times (layer caching, cache mounts, context management)

• Reducing Docker image size (multi-stage builds, minimal base images)

• Hardening container security (secret mounts, non-root users, attestations)

• Setting up CI/CD pipelines with Docker builds

• Reviewing Dockerfiles for anti-patterns

Rule Categories by Priority

Priority Category Impact Prefix

1 Layer Caching & Ordering CRITICAL cache-

2 Multi-Stage Builds CRITICAL stage-

3 Base Image Selection HIGH base-

4 Build Context Management HIGH ctx-

5 Security & Secrets HIGH sec-

6 Dependency Management MEDIUM-HIGH dep-

7 Instruction Patterns MEDIUM inst-

8 Quality & Validation MEDIUM lint-

Quick Reference

1. Layer Caching & Ordering (CRITICAL)

• cache-layer-order

• Order layers by change frequency

• cache-copy-deps-first

• Copy dependency files before source code

• cache-copy-link

• Use COPY --link for cache-efficient layer copying

• cache-mount-package

• Use cache mounts for package managers

• cache-apt-combine

• Combine apt-get update with install

• cache-external

• Use external cache for CI/CD builds

• cache-invalidation

• Avoid unnecessary cache invalidation

• cache-minimize-layers

• Consolidate related RUN instructions

2. Multi-Stage Builds (CRITICAL)

• stage-separate-build-runtime

• Separate build and runtime stages

• stage-named-stages

• Use named build stages

• stage-parallel-branches

• Exploit parallel stage execution

• stage-target-builds

• Use target builds for dev/prod

• stage-copy-artifacts-only

• Copy only final artifacts between stages

• stage-reusable-base

• Create reusable base stages

3. Base Image Selection (HIGH)

• base-minimal-image

• Use minimal base images

• base-official-images

• Use Docker Official Images

• base-pin-versions

• Pin base image versions with digests

• base-arg-version

• Use ARG before FROM to parameterize base images

• base-rebuild-regularly

• Rebuild images regularly with --pull

• base-distroless

• Use distroless or scratch images for production

4. Build Context Management (HIGH)

• ctx-dockerignore

• Use .dockerignore to exclude unnecessary files

• ctx-bind-mounts

• Use bind mounts instead of COPY for build-only files

• ctx-minimize-context

• Keep build context small

• ctx-syntax-directive

• Use syntax directive for latest BuildKit features (prerequisite for cache mounts, secret mounts, heredocs, COPY --link)

5. Security & Secrets (HIGH)

• sec-secret-mounts

• Use secret mounts for sensitive data

• sec-non-root-user

• Run as non-root user

• sec-no-secrets-in-args

• Never pass secrets via ARG or ENV

• sec-ssh-mounts

• Use SSH mounts for private repository access

• sec-attestations

• Enable SBOM and provenance attestations

• sec-no-unnecessary-packages

• Avoid installing unnecessary packages

• sec-ephemeral-containers

• Design ephemeral, stateless containers

6. Dependency Management (MEDIUM-HIGH)

• dep-cache-mount-apt

• Use cache mount for apt package manager

• dep-cache-mount-npm

• Use cache mount for npm, yarn, and pnpm

• dep-cache-mount-pip

• Use cache mount for pip

• dep-version-pin

• Pin package versions for reproducibility

• dep-cleanup-caches

• Clean package manager caches in the same layer

7. Instruction Patterns (MEDIUM)

• inst-json-cmd

• Use JSON form for CMD and ENTRYPOINT

• inst-healthcheck

• Define HEALTHCHECK for container orchestration

• inst-heredoc-scripts

• Use heredocs for multi-line scripts

• inst-entrypoint-exec

• Use exec in entrypoint scripts

• inst-workdir-absolute

• Use absolute paths with WORKDIR

• inst-copy-over-add

• Prefer COPY over ADD

8. Quality & Validation (MEDIUM)

• lint-build-checks

• Enable Docker build checks

• lint-pipefail

• Use pipefail for piped RUN commands

• lint-labels

• Use standard labels for image metadata

• lint-sort-arguments

• Sort multi-line arguments alphabetically

• lint-single-concern

• One concern per container

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels

• Rule template - Template for adding new rules

Reference Files

File Description

references/_sections.md Category definitions and ordering

assets/templates/_template.md Template for new rules

metadata.json Version and reference information