Why Multi-Stage Docker Builds Are Slowing Your CI

TL;DR: Your CI grinds to a halt because multi-stage Dockerfiles hide costly copy and commit steps. Docker’s default cache treats each stage as a fresh build, so you lose reuse. Exporting per-stage caches and mounting persistent caches flips the model and can cut CI time dramatically.

Key Takeaways - Each stage adds hidden copy/commit work that CI repeats on every run. - Docker’s default cache is scoped to the whole Dockerfile, not to individual stages. - Exporting and reusing per-stage caches with BuildKit restores the lost speed.

Most teams assume multi-stage Dockerfiles speed up CI, yet they often double build times without anyone noticing. The first stage pulls a base image, installs build tools, and compiles code. The second stage copies the compiled artifacts and discards the toolchain. On paper that looks efficient.

In reality every stage triggers a full copy of the build context, a new set of `RUN` commands, and a commit that writes a new layer. CI runners treat each `FROM … AS …` block as a separate build graph, so they cannot reuse layers that were already built in a previous stage. The result is a wall clock penalty that scales with the number of stages.

The `COPY --from=builder` line forces Docker to unpack the whole builder image, then write a new layer for the runtime image. If the builder changes even slightly, the entire second stage is invalidated. - Extra context upload for each stage. - Duplicate layer creation for copy-only steps. - Commit overhead that CI measures as build time.

These hidden steps stay invisible in most CI dashboards because they appear as a single “docker build” command. The real slowdown lives in Docker’s layer handling, not the CI server itself.

What can you do to reverse this hidden cost?

A common fix is to reorder `RUN` statements or collapse stages to reduce layer count. Those tweaks help a little, but they never address the core issue: Docker’s cache is scoped to the entire Dockerfile, not to each named stage. When a later stage depends on an earlier one, the cache treats the whole graph as a single unit.

If two pipelines share the same builder stage but differ in the final runtime stage, the runtime change still forces a rebuild of the builder because the cache key includes the downstream layers. This is why “add a dummy stage to force cache reuse” tricks rarely work.

The Docker layer basics article explains that a layer’s cache key is a hash of the command and its inputs. In a multi-stage file the inputs include the outputs of previous stages, so any change ripples forward. The BuildKit caching details page shows that BuildKit can store caches externally, but the default CI setup never tells it to reuse those caches per stage.

1. Docker reads a `RUN npm ci` line.
2. It hashes the command string and the current filesystem snapshot.
3. The snapshot contains files produced by the previous stage, even if they are unrelated to the package install.
4. When the downstream stage adds a new file, the hash for the earlier `RUN` changes, invalidating its cache.

Because the cache key spans the whole build graph, a tiny edit in `src/main.js` can invalidate the entire builder, even though the builder’s `npm ci` step never touched that file.

Understanding this mismatch uncovers a counter-intuitive fix that flips the caching model on its head. How can we make each stage independent?

BuildKit lets you name stages and export their caches with `--cache-from`. When you run a later CI job, you feed the previous job’s cache directory back into the builder. This makes each stage independent: a change in the runtime stage no longer invalidates the builder cache.

The `--mount=type=cache` flag creates a persistent volume that survives across CI runs. You can mount it inside a `RUN` step to cache package managers, compiled binaries, or language-specific caches.

By separating the cache scopes, you avoid rebuilding the builder when only the runtime changes. The per-stage cache also reduces context upload because BuildKit can reuse the already-packed layers from the local cache. - Name each stage and export its cache. - Use `--mount=type=cache` for package managers. - Combine `--target` with separate cache directories.

Let’s see how to integrate this into a CI workflow.

First, rewrite the Dockerfile with explicit stage names. The example below adds a `builder` stage and a `runtime` stage.

Next, update the CI YAML. The following GitHub Actions snippet shows how to persist the cache between jobs.

The `actions/cache` steps keep the local cache directory across workflow runs. You can replace the `docker buildx` commands with `depot.dev` remote builds for an even bigger speed boost, as described in the depot blog. - Explicit stage names make caching targets clear. - `actions/cache` persists per-stage caches between runs. - `--cache-from` and `--cache-to` wire the caches to BuildKit.

Next, we’ll look at the impact on actual build times.

When per-stage caching is in place, a CI job that previously required a lengthy rebuild can finish in roughly half the time. The reduction comes from skipping the builder stage on every change to the runtime image and from reusing package manager caches instead of redownloading dependencies.

Notice the builder steps appear only once, even though the runtime stage changed. The cache directory saved the npm layers, so the subsequent run avoided the time-consuming dependency installation step entirely.

The downstream effect is a shorter release cycle: what used to be a multi-week integration window becomes a matter of days.

How did the metrics change after the switch?

The payoff is not just speed; it’s also cost. CI minutes saved translate directly into lower cloud spend. And because the cache only stores unchanged layers, security scans that run on each layer remain effective.

For more stories on how enterprises have accelerated their pipelines, see the Customer success stories. The same approach can be applied to any language stack, from Java to Python, without sacrificing compliance or security. Which questions remain about applying this to your stack?

Q: Why do multi-stage Docker builds increase CI time?

A: Each stage repeats the copy and commit cycle, and Docker's default cache does not share layers across stages, causing redundant work.

Q: How can I enable layer caching for individual stages?

A: Name each stage, export its cache with `--cache-to`, reuse it with `--cache-from`, and mount a cache volume in `RUN` steps to keep language-specific caches persistent.

Q: Do I need to change my CI runner configuration?

A: Enable BuildKit by setting `DOCKER_BUILDKIT=1` in the environment. Most modern runners already support it, but you may need to add a step:

Q: Is `depot.dev` worth switching to for faster builds?

A: Yes, especially when combined with per-stage caching, it can accelerate builds further by offloading to a remote builder.

Q: What measurable ROI can I expect after optimizing Docker builds?

A: Teams typically see a substantial reduction in build time, freeing up CI resources and shortening release cycles. The exact gain depends on the number of stages and the size of language-specific caches.

Q: Do these optimizations affect image security?

A: No; they merely reuse unchanged layers. Security-focused stages, such as vulnerability scanning, still run on every layer because the layer content remains identical.

Related reading: - Zero Trust Mesh: Why mTLS Isn't Enough - explores security layers that complement fast builds. - Active-Active HA Is Killing Statefulness - shows how infrastructure choices ripple into CI performance. - Best Practices for CI Pipelines - broader guidance on optimizing build workflows.

What else should you explore to further optimize your pipeline?

Research and references cited in this article:

• Why Your Docker Build is So Slow: A Deep Dive into Multistage Dockerfile Optimization - DEV Community
• Multi-Stage Builds in Docker - Cycle.io
• The Shortcomings of Multi-Stage Dockerfiles | by William Bartlett
• Multi-stage builds | Docker Docs
• Understanding Multi-Stage Docker Builds - Blacksmith
• Docker Layer Caching: Speed Up CI/CD Builds | Bunnyshell
• Optimizing Docker Builds: A Practical Guide to Multi-Stage ... - Medium
• How to Implement Docker Layer Caching Strategies
• containers - Is it possible to cache multi-stage docker builds? - Stack Overflow
• Inline and local caching with multi-stage builds - General - Docker Community Forums
• Docker multi-stage build. An effective strategy to build production ...
• How to Optimize Docker Images with Multi-Stage Builds