Docker Multi-Stage Builds Cheat Sheet

Docker multi-stage Dockerfile patterns covering build stages, COPY --from, caching, and minimal final images.

2 PagesIntermediateMar 27, 2026

Multi-Stage Node.js Build

Build stage compiles TypeScript, runtime stage ships only production output.

dockerfile

# syntax=docker/dockerfile:1FROM node:20-alpine AS depsWORKDIR /appCOPY package.json package-lock.json ./RUN npm ciFROM deps AS buildCOPY . .RUN npm run buildFROM node:20-alpine AS runtimeWORKDIR /appENV NODE_ENV=productionCOPY package.json package-lock.json ./RUN npm ci --omit=devCOPY --from=build /app/dist ./distUSER nodeEXPOSE 3000CMD ["node", "dist/main.js"]

Multi-Stage Go Build (Scratch Final Image)

Compile a static binary, then ship it with no OS layer at all.

dockerfile

FROM golang:1.23-alpine AS buildWORKDIR /srcCOPY go.mod go.sum ./RUN go mod downloadCOPY . .RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /app ./cmd/serverFROM scratch AS runtimeCOPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/COPY --from=build /app /appENTRYPOINT ["/app"]

BuildKit Cache Mounts & Build-Time Args

Speed up rebuilds with persistent cache mounts and multi-target builds.

dockerfile

# syntax=docker/dockerfile:1FROM golang:1.23-alpine AS buildWORKDIR /srcCOPY go.mod go.sum ./RUN --mount=type=cache,target=/go/pkg/mod \    --mount=type=cache,target=/root/.cache/go-build \    go mod downloadCOPY . .RUN --mount=type=cache,target=/root/.cache/go-build \    go build -o /app ./cmd/server# Build only the 'build' stage for debugging:#   docker build --target build -t app:debug .# Build final stage (default):#   docker build -t app:latest .

Key Directives & Flags

Instructions and CLI flags specific to multi-stage builds.

FROM <image> AS <name>- names a stage so later stages can reference it
COPY --from=<stage|image>- copies files from a previous stage or an external image, not the build context
--target <stage>- `docker build --target <name>` builds only up to that stage
--mount=type=cache- BuildKit cache mount that persists across builds without bloating the image layer
FROM scratch / distroless- empty or near-empty base for the final stage, minimizes attack surface and size
--mount=type=secret- injects a secret into a RUN step without leaving it in any image layer

Pro Tip

Order COPY instructions from least to most frequently changed (dependency manifests before source code) so BuildKit's layer cache survives across builds where only your application code changed — a `COPY . .` before `npm ci` invalidates the dependency layer on every commit.

Was this cheat sheet helpful?

Renovate Bot Cheat Sheet

Kubernetes Operators Cheat Sheet