Let’s define the concept precisely before exploring why it matters so much.

A build recipe split into distinct phases

A multi-stage build is a way of writing an image’s build recipe as several distinct, separate phases — called stages — instead of one single, continuous phase. Each stage can use its own starting point, install its own tools, and produce its own intermediate output. Crucially, only the parts you deliberately choose to carry forward from one stage to the next actually make it into the final image; everything else used along the way is simply left behind.

Building something versus shipping something

The core insight behind multi-stage builds is recognizing that “building” an application and “running” an application are two fundamentally different activities, with two fundamentally different sets of requirements. Building often needs compilers, build tools, source code, and temporary intermediate files. Running usually needs none of that — just the finished, compiled result and whatever minimal runtime it depends on. A multi-stage build lets each of these activities happen in its own dedicated stage, using exactly the tools each one actually needs.

To appreciate the design, it helps to fully understand the pain that came before it.

Problem 1 — Bloated final images

Before multi-stage builds existed, a common pattern was to install every build tool needed to compile or prepare an application directly into the same image that would eventually run in production. Compilers, build systems, development headers, and source code all ended up permanently baked into the shipped image — often making it many times larger than it needed to be, purely because of tools that were only ever needed once, during the build itself.

Problem 2 — A larger, harder-to-secure attack surface

Every extra tool and library included in a final image is also extra surface area for potential security vulnerabilities. A compiler sitting in a production image isn’t just wasted space — it’s also one more piece of software that could theoretically be exploited, despite never actually being needed once the application is built and running.

Problem 3 — Awkward workarounds

Before multi-stage builds, teams trying to avoid this bloat had to resort to more fragile workarounds: building an application in a completely separate process outside of Docker entirely, then manually copying the finished result into a minimal image afterward. This worked, but it split the build process across two disconnected systems, making it harder to keep the whole process reproducible, portable, and self-contained within a single build definition.

Seeing the two approaches side by side makes the benefit concrete.

The single-stage approach

In a single-stage build, everything happens in one continuous sequence, starting from one base and ending with one image. Build tools are installed, source code is compiled or prepared, and the final application is placed — all within that same, single, ever-growing set of layers. Whatever was installed to build the application remains present in the final result, whether it’s still needed or not.

The multi-stage approach

In a multi-stage build, the build tools and processes live entirely in one or more earlier stages, each starting fresh from whatever base makes sense for that specific job. The final stage then starts from a separate, typically much smaller and more minimal base, and deliberately copies over only the specific, finished output it actually needs from the earlier stage — leaving every build tool, every intermediate file, and every piece of source code behind in the discarded earlier stage.

Let’s break down the structural pieces that make up a multi-stage build.

Stages

A stage is one distinct phase of the build, with its own starting base and its own sequence of steps. Each stage is, in a sense, its own mini build process — capable of installing whatever tools it specifically needs, without affecting or being affected by any other stage’s tools.

Stage bases

Every stage begins from a chosen starting image, exactly the same way a regular, single-stage build does. Different stages are free to start from completely different bases — a build stage might start from a base loaded with compilers and development tools, while the final stage might start from an extremely minimal base containing almost nothing beyond what’s strictly needed to run the finished application.

Named stages

Stages can be given a name, purely for clarity and for later reference. Naming a stage makes it much easier to refer back to it — especially when copying specific output from it into a later stage — rather than having to track stages only by their position in the sequence.

The final stage

The very last stage defined in the build is what actually becomes the resulting image. Everything from earlier stages exists only temporarily, during the build process itself, and is discarded once the build finishes — unless something was deliberately copied forward into this final stage.

flowchart LR
    subgraph "Stage 1: Build"
    A[Base with Build Tools] --> B[Install Dependencies]
    B --> C[Compile / Prepare Application]
    end
    subgraph "Stage 2: Final"
    D[Minimal Base] --> E[Copy Finished Output Only]
    end
    C -.copy artifact.-> E
    E --> F[Final Docker Image]
        

Now let’s go deeper into what Docker’s build engine actually does when it encounters a multi-stage build definition.

Parsing the full sequence first

Before executing anything, the build engine reads through the entire build definition and identifies every stage present, along with each stage’s chosen base and its position (or name) in the sequence. This full picture is what allows the engine to reason about dependencies between stages before actually running any of them.

Building each stage as its own isolated environment

Each stage is built as its own isolated filesystem environment, layered from its own chosen base, exactly as if it were an independent build on its own. Nothing installed in one stage is automatically visible inside another stage — isolation between stages is the default, not the exception.

The explicit copy step as the only bridge

The only way content moves from one stage into another is through an explicit instruction to copy specific files or directories from a named (or numbered) earlier stage into the current one. This is a deliberate, narrow bridge — nothing crosses between stages unless specifically instructed to, which is exactly what keeps unrelated build tools and intermediate files from leaking into the final result.

Discarding everything not carried forward

Once the build finishes, any stage that isn’t the final stage is not preserved as part of the resulting image. Their layers may briefly exist in a build cache (covered further in Chapter 9), but they are not part of what gets tagged, stored, or shipped as the finished image.

sequenceDiagram
    participant E as Build Engine
    participant S1 as Stage 1 (Build)
    participant S2 as Stage 2 (Final)
    E->>E: Parse full build definition
    E->>S1: Build in isolation from its own base
    S1-->>E: Stage 1 complete, output ready
    E->>S2: Build in isolation from its own base
    E->>S2: Copy specific output from Stage 1
    S2-->>E: Stage 2 complete
    E->>E: Tag Stage 2's result as the final image
        

Because this copy step is the single most important mechanic in the entire multi-stage system, it deserves its own dedicated exploration.

Referencing an earlier stage by name or position

A later stage can reference an earlier one either by the name explicitly given to it, or by its numeric position in the overall sequence. Referencing by name is generally considered clearer and more maintainable, since it doesn’t silently break if stages are reordered or new ones are inserted later.

Copying only what’s actually needed

A copy instruction is deliberately narrow — it targets specific files or folders from the source stage, not the entire stage’s filesystem. This precision is what allows a final stage to pick up, say, just one compiled application binary, or just one folder of finished static assets, while leaving behind everything else that stage contained.

Copying from external sources too

Interestingly, this same copying mechanism isn’t limited to referencing only your own earlier stages — it can also pull specific files directly from other, already-built images entirely, treating them the same way as an internal stage. This is a powerful pattern for grabbing a specific, pre-built tool or component from an existing image, without needing to reproduce however that image was originally built.

A powerful, often underused capability of multi-stage builds is that you’re not limited to only ever producing the very last stage.

Targeting an earlier stage directly

Rather than always building all the way through to the final stage, it’s possible to explicitly tell the build engine to stop at, and produce the result of, a specific earlier stage instead. This effectively lets one multi-stage definition serve multiple different purposes depending on which stage is targeted.

A single definition, multiple useful outputs

This capability is commonly used to define, for example, a “development” stage that includes debugging tools and a full development environment, alongside a “production” final stage that’s stripped down to the bare minimum — all described once, in a single shared definition, rather than maintaining two separate, easily-diverging build definitions.

Reducing duplication and drift

Because all these variants share the same earlier stages (like a common dependency-installation stage), keeping them in one definition significantly reduces the risk of the different variants slowly drifting apart from each other over time, which is a very real risk when equivalent logic is duplicated across separate, independently maintained files.

Multi-stage builds interact with Docker’s layer caching system in some important, non-obvious ways.

Each stage caches independently

Because each stage is its own isolated build, each one benefits from layer caching independently — if an earlier stage’s steps haven’t changed since the last build, that stage’s layers can often be reused directly from cache, skipping the work of rebuilding them entirely.

Why stage ordering still matters for caching

Just as with single-stage builds, the order of steps within a stage affects how effectively caching works: steps that change frequently (like copying in fresh source code) should generally come after steps that change rarely (like installing dependencies), so that a small code change doesn’t force the rarely-changing steps to be needlessly rebuilt too.

Reusing stages across separate builds

Because a named stage is itself just a build with its own set of cacheable layers, a stage that’s shared conceptually across multiple different final targets (as described in Chapter 8) can potentially have its cache reused across all of them, rather than being rebuilt separately for each variant.

A subtler architectural benefit of multi-stage builds involves how independent, unrelated stages can be handled efficiently.

Stages without a dependency relationship

Not every stage in a multi-stage build necessarily depends on another. For example, one stage might prepare backend application code while a completely separate stage prepares frontend static assets — two efforts that don’t rely on each other’s output at all, only converging later when both are copied into a shared final stage.

Why this separation is valuable beyond just cleanliness

Because the build engine understands the full dependency graph between stages (from parsing the whole definition upfront, as covered in Chapter 5), it can recognize when two stages have no dependency relationship between them, opening the door to handling genuinely independent work more efficiently than if everything were forced into one strict, linear sequence.

A cleaner mental model, regardless

Even setting aside efficiency considerations, structuring genuinely unrelated pieces of work as separate stages keeps the overall build definition easier to read and reason about — each stage tells a focused, self-contained story, rather than mixing unrelated concerns together in one long, tangled sequence.

flowchart TD
    A[Stage: Backend Build] --> C[Final Stage]
    B[Stage: Frontend Build] --> C
    C --> D[Final Docker Image]
        

Multi-stage builds are, at their core, a meaningful security improvement — but they’re not a complete security solution on their own.

Real reduction in shipped attack surface

The most direct security benefit is straightforward: a final image that never includes a compiler, a package manager’s full toolchain, or leftover source code has genuinely fewer things that could ever be exploited, compared to an equivalent single-stage image carrying all of that along unnecessarily.

Secrets can still leak within a stage

Multi-stage builds don’t automatically solve the problem of sensitive information (like credentials needed only during the build itself) becoming permanently baked into a stage’s own layers. If a build stage’s layers were somehow carried forward, or if the pattern of secret-handling isn’t done carefully, sensitive data can still end up somewhere it shouldn’t.

The final stage’s base still matters enormously

Multi-stage builds reduce what makes it into the final image, but the final stage’s own starting base still needs to be chosen and maintained carefully — a minimal final stage built from an outdated or unverified base image inherits whatever risks that base carries, regardless of how clean the earlier build stages were.

Multi-stage builds benefit from their own kind of ongoing visibility, distinct from monitoring a running application.

Tracking final image size over time

Since one of the main goals of multi-stage builds is a smaller final image, tracking how that size changes across builds is a direct, meaningful signal — a sudden, unexpected size increase often indicates something unintended was accidentally carried into the final stage.

Per-stage build duration

Tracking how long each individual stage takes to build helps pinpoint exactly where time is being spent, and where caching improvements or restructuring might have the biggest impact, rather than only having visibility into the total build time as one lump figure.

Cache hit rates per stage

Understanding how often each stage’s layers are successfully reused from cache versus rebuilt from scratch reveals whether the build’s step ordering (Chapter 9) is genuinely working in your favor, or quietly undermining itself.

Good pattern — one stage, one clear responsibility

Just as with the containers themselves, well-designed stages each focus on one clear job — installing dependencies, compiling code, preparing static assets — rather than mixing multiple unrelated responsibilities into a single sprawling stage.

Good pattern — minimal final stage base

Deliberately choosing the smallest, most minimal reasonable base for the final stage — including only what the running application genuinely requires — maximizes the size and security benefits multi-stage builds are meant to provide.

By default, no — only the last stage becomes the resulting image. Earlier stages exist only temporarily during the build, unless you explicitly target one of them directly as an alternate output.

Not directly. Stages are isolated from each other — only files explicitly copied over using the copy mechanism cross between stages. Installed tools themselves stay confined to the stage that installed them, unless the tool’s own output files are specifically copied forward.

Yes. Each stage caches independently, just like a regular build would, which is exactly why well-ordered steps within each stage can meaningfully speed up rebuilds even though those stages aren’t part of the final shipped image.

Yes. The same copy mechanism that pulls content from an earlier stage can also pull specific files directly from an already-built image, treating it much like an additional stage for this purpose.

No. While compiled languages are a particularly clear example, any workflow with a meaningful gap between “what’s needed to build” and “what’s needed to run” — including frontend asset bundling or heavy dependency installation — can benefit from the same separation.

Multi-stage builds solve a very real, very common problem: the tools and processes needed to build an application are usually completely different from what’s needed to actually run it, yet for a long time, Docker images carried both bundled permanently together. By splitting a build definition into distinct, isolated stages — each with its own base and its own purpose — and deliberately copying forward only the specific, finished output that’s actually needed, multi-stage builds produce final images that are smaller, more secure, and easier to reason about, all while staying within a single, self-contained, reproducible build definition. Understanding how stages are isolated, how the copy mechanism acts as the only bridge between them, how caching behaves per stage, and how to target multiple useful variants from one shared definition is what separates a build definition that merely works from one that’s genuinely production-grade.