Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 37 ยท Building and Registries

Multi-Stage Builds and Build Caching

Shrink images with multi-stage Containerfiles, use cache mounts, build for several architectures with manifest lists, and inspect image history and size with Podman.

Building software usually needs tools (compilers, package managers, headers) that you do not want in the image you ship. Shipping them makes images large, slow to pull and bigger targets for attackers. A multi-stage build solves this: you compile in one stage with all the tools, then copy only the finished result into a clean, small final stage.

This lesson shows multi-stage Containerfiles, build cache mounts, targeted builds for testing, and multi-architecture images. Builds need a real Podman, so commands are read-only; the stand-ins analyze which stages end up in the final image and how multi-arch manifests are organized.

One file, several stages

Each FROM starts a new stage. Name stages with AS and copy between them with COPY --from=:

DOCKERFILE
# Stage 1: build
FROM docker.io/library/golang:1.24 AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /out/server ./cmd/server

# Stage 2: run
FROM docker.io/library/alpine:3.21
RUN adduser -D app
USER app
COPY --from=build /out/server /usr/local/bin/server
EXPOSE 8080
ENTRYPOINT ["/usr/local/bin/server"]

Only the last stage becomes the final image (unless you pick another with --target). The Go toolchain, the source code and the module cache stay behind in stage 1; the final image contains Alpine and one binary.

Multi-stage build

Build stage Compilers and tools.
COPY --from Take only the output.
Final stage Small and clean.

Tools stay in the build stage.

1 / 2

Typical savings are large: a Go or Rust program can drop from over a gigabyte to a few megabytes; a Node or Java app loses its build tools and dev dependencies.

Which stages reach the final image?

Podman's build skips stages that the final image does not depend on (the --skip-unused-stages option, on by default). A plain read of the file shows how data flows. This stand-in parses a Containerfile, finds the stage dependencies and prints which stages contribute to the final image.

Python Stage graph (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The test stage is skipped for a normal build and runs only if you ask for it:

Terminal
podman build --target test -t myapp:test .
podman build -t myapp:1.0 .

Cache mounts

Package managers re-download the same files on every build when a layer is invalidated. A cache mount keeps a directory between builds without storing it in a layer:

DOCKERFILE
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.txt

RUN --mount=type=cache,target=/go/pkg/mod \
    go build -o /out/server ./cmd/server

The cache lives in Podman's storage, speeds up repeated builds, and never ends up in the image. Bind mounts (--mount=type=bind,source=.,target=/src) let a RUN read your files without copying them into a layer.

Looking inside an image

Terminal
podman images
podman image history localhost/myapp:1.0
podman image inspect localhost/myapp:1.0 --format '{{.Size}}'
podman image tree localhost/myapp:1.0

history lists each layer with the instruction that made it and its size: a quick way to find the step that bloated the image. Common culprits are a package install without cleanup, COPY . . that included node_modules, and a downloaded archive that was removed in a later layer (deleting a file in a later layer does not shrink earlier ones).

Multi-architecture images

A manifest list (or "image index") is a small document that maps platforms to images, so the same name works on amd64 and arm64. Podman builds them with podman manifest:

Terminal
podman build --platform linux/amd64 -t localhost/myapp:amd64 .
podman build --platform linux/arm64 -t localhost/myapp:arm64 .
podman manifest create localhost/myapp:1.0
podman manifest add localhost/myapp:1.0 localhost/myapp:amd64
podman manifest add localhost/myapp:1.0 localhost/myapp:arm64
podman manifest push --all localhost/myapp:1.0 docker://registry.example.com/myapp:1.0

Building a platform that differs from your host needs emulation (QEMU user-mode binaries, usually the qemu-user-static package), and the build runs much slower. When a user pulls myapp:1.0, the runtime reads the manifest list and picks the entry for its own architecture.

Python Pick the right image from a manifest list (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Practical checklist

  • Name your stages and keep the final stage minimal (a slim, alpine or distroless base).
  • Copy dependency manifests first, install, then copy the source.
  • Use cache mounts for package managers.
  • Build a --target test stage in CI without changing the production image.
  • Check podman image history after changes to see what grew.

Continue with Registries and Authentication to learn how to publish what you built.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which image becomes the final result of a multi-stage Containerfile by default?

    The last FROM stage is the output unless you choose another with --target.
  2. 2. What does COPY --from=build /out/app /app do?

    --from refers to a previous stage (or another image) as the source of the copy.
  3. 3. What is the benefit of RUN --mount=type=cache?

    The cache directory persists in Podman storage across builds but never ends up in the image.
  4. 4. Deleting a large file in a later RUN instruction...

    Layers are additive. Remove files in the same RUN that created them, or use a multi-stage build.

Summary

  • Multi-stage builds compile in one stage and copy only the output into a small final stage with COPY --from=.
  • --target stops a build at a named stage; unneeded stages are not part of the final image.
  • Cache mounts and bind mounts speed up builds without bloating layers.
  • podman image history shows what each layer costs.
  • Manifest lists let one image name serve several CPU architectures.

Next: Registries and Authentication