Multi-stage builds — separating build from runtime · Docker & Containers

A multi-stage build lets you compile in a fat image and ship a thin one. The build stage has the toolchain (compilers, package managers, source). The runtime stage has only what the application needs at runtime. The image you ship is the runtime stage.

A complete multi-stage example

# syntax=docker/dockerfile:1

# Stage 1: build
FROM golang:1.24 AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    go mod download
COPY . .
RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags="-s -w" -o /out/app

# Stage 2: runtime
FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=build --chown=nonroot:nonroot /out/app /app
USER nonroot:nonroot
EXPOSE 8080
ENTRYPOINT ["/app"]

The final image contains:

Distroless base: ~2 MB.
The static binary: ~10–30 MB.
Nothing else.

Total: ~12–32 MB. The Go toolchain (1+ GB) is gone.

Why multi-stage is the right default

Without multi-stage, the same image is used for build and runtime. That means:

The compiler is in the production image. Wasted space and attack surface.
Source code may be in the image (depending on COPY/.dockerignore).
Build artefacts (node_modules, target/) are in the image.

A multi-stage build is not just smaller; it is a smaller attack surface. The runtime image does not have a compiler, so even if an attacker exploits a vulnerability in the application, they cannot recompile a payload on the host.

Where the build stage actually goes

“The build stage is not in the final image” is true. It is also narrower than people hear it, and the gap is where a real class of disclosure lives.

Not in the manifest, very much in the content store

BuildKit executes each stage as its own branch of the build graph and produces a filesystem snapshot for every step in it. Those snapshots are real content in the builder’s store — the compiler output, the full source tree the COPY . . pulled in, every dependency the package manager downloaded.

What the manifest of your final image references is only the layers of the last stage, or of the stage named by --target. Layers belonging to build are simply never listed, so a client pulling the image never receives them and docker history on the image cannot see them. That is the whole trick: there is no scrubbing step, the layers just are not named.

They are, however:

On the build host, in the builder’s cache, for as long as the cache retains them. docker buildx du --verbose lists them.
Reusable, which is exactly why they are kept. The next build that changes only the runtime stage reuses the compiled output instead of recompiling. This is the mechanism people are relying on when they say multi-stage builds are fast.
Exportable. --cache-to=…,mode=max deliberately exports every layer “even those of intermediate steps”, where mode=min exports “only layers that are exported into the resulting image”.

So a mode=max cache pushed to a registry contains your build stage: source tree, private dependencies, anything a RUN wrote and a later stage did not copy.

The public cache tag that shipped the source tree

A team makes their application image public — an open-source release, or a customer-facing sidecar — and the image is clean. Multi-stage, distroless runtime, 14 MB, one binary, audited.

The CI job also pushes its build cache:

docker buildx build \
  --cache-to=type=registry,ref=myorg/myapp:buildcache,mode=max \
  --push -t myorg/myapp:1.0.0 .

myorg/myapp:buildcache is in the same repository, with the same visibility, and mode=max means it holds every intermediate layer: the whole source tree copied by COPY . ., the .npmrc a RUN step happened to write, the private packages installed before the artefacts were copied forward.

Nobody looks at it because it is not an image you can run, and docker pull of the cache tag produces something unhelpful. But docker buildx imagetools inspect reads it fine, and so does any OCI client.

The first diagnosis when this is discovered is usually “the image must have leaked” — and the image is spotless, which sends people in circles. Check the cache ref.

Fix it by putting the cache somewhere with its own access control: a private repository, an internal registry, or type=s3 in a bucket that is not the public one. Verify with docker buildx imagetools inspect myorg/myapp:buildcache and by checking the repository’s visibility, not by assuming it inherited anything.

Named stages

Use AS name to give stages readable names:

FROM node:22 AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

FROM node:22 AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM nginx:1.27 AS runtime
COPY --from=build /app/dist /usr/share/nginx/html

This reads top-to-bottom: deps, build, runtime. The runtime stage is what you ship.

What `COPY --from` can point at

Per the Dockerfile reference, “the COPY --from flag lets you copy files from an image, a build stage, or a named context instead” of the build context. Four forms are worth knowing:

Form	Example	Use
Stage name	`COPY --from=build /out/app /app`	The normal case
Stage index	`COPY --from=0 /out/app /app`	Unnamed stages; avoid, it breaks on reorder
External image	`COPY --from=nginx:1.27 /etc/nginx/mime.types /etc/`	Lift one file out of a published image
Named context	`COPY --from=docs /site /usr/share/nginx/html`	Paired with `--build-context docs=./website`

The external-image form is genuinely useful and under-used: it is how you get ca-certificates or a single CLI binary into a distroless image with no package manager.

FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=alpine:3.21 /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=build /out/app /app
ENTRYPOINT ["/app"]

`COPY --link`

--link changes the semantics so that, in Docker’s words, “files remain independent on their own layer and don’t get invalidated when commands on previous layers are changed.”

In a multi-stage build that is worth real time. Without it, bumping the runtime base image invalidates the COPY --from=build that follows it, so the artefact layer is rebuilt and re-pushed even though the artefact is byte-identical. With --link, the artefact layer is reused and only the base layers change.

FROM gcr.io/distroless/static-debian12:nonroot
COPY --link --from=build /out/app /app

The trade-off: a --link copy does not see the destination image’s filesystem, so it cannot resolve a user name for --chown against that image’s /etc/passwd and it will not follow symlinks that exist only in the base. Use numeric IDs with it.

Targeting a specific stage

You can build only one stage of a multi-stage Dockerfile:

docker buildx build --target deps --tag myorg/myapp:deps .

This is useful for CI where you want to share the deps stage across multiple test stages.

BuildKit builds only what the target’s ancestry requires. A stage that nothing references is not in the graph and never executes — which is why you can keep a test stage and a lint stage in the same Dockerfile without paying for them in the production build.

exec /app: no such file or directory — on a file that is definitely there

FROM golang:1.24 AS build
WORKDIR /src
COPY . .
RUN go build -o /out/app        # note: no CGO_ENABLED=0

FROM alpine:3.21
COPY --from=build /out/app /app
ENTRYPOINT ["/app"]

$ docker run --rm myorg/myapp:dev
exec /app: no such file or directory

The file exists. docker run --rm --entrypoint ls myorg/myapp:dev -l /app prints it, with the right size and the execute bit set. People spend a long time on the path, the working directory, the entrypoint form, and line endings.

The missing file is not /app. It is the dynamic loader. golang:1.24 is Debian-based with glibc; with cgo enabled — which it is by default whenever a package such as net or os/user is in play — the binary is dynamically linked against /lib64/ld-linux-x86-64.so.2. Alpine ships musl and has no such file. The kernel’s execve fails because the interpreter named in the ELF header does not exist, and the error it returns is the same ENOENT you would get from a missing binary.

The same failure appears whenever the build stage and the runtime stage disagree about libc: Debian build into Alpine runtime, or anything dynamically linked into scratch or distroless/static-*.

Three fixes, in order of preference:

Build a static binary: CGO_ENABLED=0 go build ….
Match the libc: build in golang:1.24-alpine, run on Alpine.
Use a runtime base that carries glibc: gcr.io/distroless/base-debian12.

Verifying the artefact before you ship it

The failure above is entirely preventable, in the build stage, with a check that fails the build rather than the container.

FROM golang:1.24 AS build
WORKDIR /src
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -o /out/app
# Fail here, not at 03:00 in production.
RUN ldd /out/app 2>&1 | grep -q 'not a dynamic executable' \
 || (echo 'FAIL: /out/app is dynamically linked; it will not run on scratch or static-distroless' && exit 1)

ldd on a static binary reports not a dynamic executable; on a dynamic one it lists the loader and the shared objects. That single RUN converts a runtime mystery into a build error with the reason in the message.

For an image you have already built, ask the image itself:

Read-only / Safelayer count— A runtime image built from a static binary onto a static base should have very few layers and no toolchain.

$ docker image inspect --format '{{len .RootFS.Layers}} layers, {{.Size}} bytes' myorg/myapp:1.0.0

3 layers, 14238720 bytes

Illustrative output

Read-only / Safewhat is in there— List every path in the shipped image. On a correct multi-stage build this is short enough to read.

IMAGE=myorg/myapp:1.0.0
docker save "$IMAGE" | tar -xO --wildcards '*/layer.tar' | tar -tv | head -50

If a compiler, a .git directory, or your source tree appears in that listing, the multi-stage split did not do what you assumed.

Common mistakes

What if you need a shell in the build stage to work out why the compile failed?

Build the intermediate stage on purpose and run it. Because the stage is already in the builder’s cache, this costs almost nothing.

docker buildx build --target build --load -t myorg/myapp:buildstage .
docker run --rm -it myorg/myapp:buildstage bash

You are now standing in exactly the filesystem the failing RUN saw, with the toolchain present and the source where the build put it. Re-run the compile by hand, inspect paths, check environment variables.

Two cautions. --load is required for any non-default builder, and the resulting tag is a full fat toolchain image — tag it something obviously disposable and remove it afterwards, because an image called myorg/myapp:buildstage sitting in a registry is precisely the artefact the multi-stage build existed to avoid publishing.

If the failing step is deeper than the stage boundary, --no-cache-filter <stage> forces just that stage to re-run so you can watch it with --progress=plain.