Why Multi-Stage Builds Exist
Compiling an application often requires heavy tooling — compilers, build systems, dev dependencies — that has no place in the final runtime image. Before multi-stage builds, developers either shipped bloated images containing build tools, or maintained separate Dockerfiles and manually copied artifacts between them. Multi-stage builds solve this within a single Dockerfile by allowing multiple FROM instructions, each starting a new, independent build stage.
Cricket analogy: Like a franchise running heavy pre-season nets at the academy with bowling machines and extra coaches, then sending only the fit playing XI onto the MCG pitch — multi-stage builds keep compilers in an early stage and ship only the finished binary.
Naming and Referencing Stages
Each stage can be given a name with FROM <image> AS <name>. A later stage can then selectively copy artifacts out of an earlier stage using COPY --from=<name>, pulling in only the compiled output rather than the entire build environment.
Cricket analogy: Like naming a specific net session 'spin practice' so the head coach can later pull only Ravichandran Ashwin's drills from it, COPY --from=<name> pulls named artifacts out of an earlier build stage instead of the whole session.
# Stage 1: build the Go binary
FROM golang:1.22 AS builder
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /out/app .
# Stage 2: minimal runtime image
FROM alpine:3.20
RUN apk add --no-cache ca-certificates
COPY --from=builder /out/app /usr/local/bin/app
USER nobody
ENTRYPOINT ["/usr/local/bin/app"]Only the final stage in the Dockerfile becomes the resulting image by default. Every earlier stage exists only during the build and is discarded afterward (though its layers may remain cached locally for faster rebuilds), so the Go compiler, source code, and module cache never end up in the shipped image.
Building a Specific Stage
The --target flag lets you build and stop at a specific named stage, which is useful for producing a debug or test image that includes build tooling, separate from the lean production image.
Cricket analogy: Like a warm-up match that's stopped after the top order bats so selectors can assess just that portion without playing the full fixture, --target lets you build and stop at one named stage for a debug image.
# Build only up through the 'builder' stage (e.g. for running unit tests)
docker build --target builder -t myapp:builder .
# Build the full multi-stage Dockerfile (defaults to the last stage)
docker build -t myapp:prod .Copying From External Images
COPY --from isn't limited to stages defined in the same Dockerfile — it can also copy files from any other image, which is handy for grabbing a single static tool without installing an entire package.
Cricket analogy: Like borrowing just Jasprit Bumrah's specific match-worn boots from another team's kit bag instead of taking their entire equipment trunk, COPY --from can pull a single artifact from any image, not just your own build stages.
FROM alpine:3.20
# Copy a statically built tool directly from its published image
COPY --from=hashicorp/terraform:1.8 /bin/terraform /usr/local/bin/terraformBenefits: Size, Security, and Simplicity
Multi-stage builds typically shrink final image size dramatically (a Go build image might be 900MB+, while the resulting Alpine-based runtime image can be under 20MB) because compilers, source code, and package caches are never copied into the final stage. Smaller images also mean a smaller attack surface, since tools like compilers and shells that could aid an attacker post-compromise are simply absent.
Cricket analogy: Like trimming a bloated 30-player touring squad down to the lean 11 who actually walk out to bat, dropping the physios' full medical trunk, multi-stage builds shrink a 900MB build image to under 20MB by dropping compilers and caches.
Multi-stage builds reduce the size of the final image but do not automatically reduce the total time or disk used during the build itself — earlier stages still execute in full (though their layers benefit from the normal build cache). Multi-stage builds optimize what ships, not necessarily what gets built.
- A single Dockerfile can contain multiple FROM instructions, each starting a new build stage.
- Name a stage with
FROM image AS name, then pull artifacts from it viaCOPY --from=name. - Only the final stage becomes the built image; earlier stages are discarded from the shipped result.
docker build --target <stage>builds and stops at a specific intermediate stage.- COPY --from can also reference an entirely separate, already-published image, not just a local stage.
- Multi-stage builds shrink final image size and attack surface by excluding compilers and build-only dependencies.
Practice what you learned
1. In a multi-stage Dockerfile, which stage becomes the final built image by default?
2. What does `COPY --from=builder /out/app /usr/local/bin/app` do?
3. What is the main benefit of multi-stage builds regarding final image size?
4. What does `docker build --target builder .` do in a multi-stage Dockerfile?
5. Can COPY --from reference an image that isn't a stage within the current Dockerfile?
Was this page helpful?
You May Also Like
Writing a Dockerfile
A practical guide to Dockerfile syntax and the core instructions used to build a custom image from scratch.
Image Layers and Build Caching
How Docker's layered filesystem and build cache work, and how to order Dockerfile instructions to maximize cache hits and minimize image size.
Image Size Optimization
Techniques for shrinking Docker images through multi-stage builds, minimal base images, and layer-aware Dockerfile authoring to speed up builds and deployments.
Docker Security Basics
Defensive practices for hardening container images and runtime, including non-root users, minimal base images, vulnerability scanning, and dropped capabilities.
Related Reading
Related Study Notes in DevOps
Browse all study notesNginx Study Notes
DevOps · 30 topics
DevOpsAnsible Study Notes
DevOps · 30 topics
DevOpsAdvanced Kubernetes Study Notes
Kubernetes · 30 topics
DevOpsAdvanced Bash Scripting Study Notes
Bash · 30 topics
DevOpsApache Kafka Study Notes
Kafka · 30 topics
DevOpsCI/CD Tools & Pipelines Study Notes
YAML · 37 topics