OpsCanary
cicdcontainersPractitioner

Mastering Multi-Stage Builds in Dockerfiles

5 min read Docker DocsNov 22, 2026Reviewed for accuracy
Share
Practitioner — Hands-on experience recommended

Multi-stage builds exist to streamline the Docker image creation process. They solve the problem of bloated images by allowing you to use multiple FROM statements within a single Dockerfile. This means you can compile your application in one stage and only copy the final artifact to a much smaller base image in another stage, keeping your images clean and efficient.

Each FROM instruction starts a new build stage, which can use a different base image. For example, you can begin with a full-fledged language runtime like Golang to build your application, and then transition to a minimal image like scratch for the final output. The COPY --from instruction enables you to selectively pull artifacts from previous stages, ensuring that only the necessary files make it into your final image. This not only reduces the image size but also enhances security by minimizing the attack surface.

In production, you need to be aware of how BuildKit operates. By enabling BuildKit with the DOCKER_BUILDKIT environment variable, you can optimize your builds further, as it only builds the stages that the target stage depends on. This can significantly speed up your build times, especially in CI/CD pipelines. However, be cautious with complex multi-stage setups; they can introduce confusion if not documented properly. Always ensure that your Dockerfiles remain readable and maintainable, as this will save you headaches down the line.

Key takeaways

  • →Use multiple FROM statements to optimize Dockerfiles and reduce image size.
  • →Leverage COPY --from to selectively copy artifacts between stages.
  • →Enable BuildKit with DOCKER_BUILDKIT=1 for faster builds in CI/CD pipelines.
  • →Document complex multi-stage builds to maintain readability and ease of maintenance.
  • →Be mindful of the base images you choose for each stage to optimize performance.

Why it matters

In production, smaller Docker images lead to faster deployments and reduced resource consumption. This can significantly impact your CI/CD pipeline efficiency and overall application performance.

Code examples

Dockerfile
1# syntax=docker/dockerfile:1
2FROM golang:1.26
3WORKDIR /src
4COPY <<EOF ./main.go
5package main
6import "fmt"
7func main() {
8	fmt.Println("hello, world")
9}
10EOF
11RUN go build -o /bin/hello ./main.go
12FROM scratch
13COPY --from=0 /bin/hello /bin/hello
14CMD ["/bin/hello"]
Dockerfile
1# syntax=docker/dockerfile:1
2FROM golang:1.26 AS build
3WORKDIR /src
4COPY <<EOF /src/main.go
5package main
6import "fmt"
7func main() {
8	fmt.Println("hello, world")
9}
10EOF
11RUN go build -o /bin/hello ./main.go
12FROM scratch
13COPY --from=build /bin/hello /bin/hello
14CMD ["/bin/hello"]
Dockerfile
$ docker build --target build -t hello .

When NOT to use this

The official docs don't call out specific anti-patterns here. Use your judgment based on your scale and requirements.

Want the complete reference?

Read official docs

Test what you just learned

Quiz questions written from this article

Take the quiz →
RailwaySponsor

Deploy any app in seconds — no infrastructure config, no DevOps overhead. Instant deployments from GitHub, built-in databases, and automatic scaling.

Start deploying free →

Get the daily digest

One email. 5 articles. Every morning.

No spam. Unsubscribe anytime.