How does Docker multi-stage build layer caching work?

A multi-stage build uses several FROM instructions in one Dockerfile. Early stages carry compilers, package managers and source code. The final stage starts from a small runtime base and uses COPY --from to take only the built artifacts. The shipped image contains only the final stage's layers, so build tooling never reaches production.

Each instruction produces a layer, and the builder looks it up in a cache before running it. The cache key combines the parent layer with the instruction text. For COPY and ADD, the key also includes checksums of the files being copied. For RUN, only the command string counts. A RUN step is not re-executed just because a remote package registry changed.

Because the parent layer is part of every key, the first miss in a stage changes the parent of everything after it. Every later layer in that stage rebuilds, even if its own instruction is identical. This makes layer order the main lever. Put inputs that change rarely, such as the base image and dependency manifests, before inputs that change often, such as source code.

On a code-only change:

 BUILD STAGE                          RUNTIME STAGE
 FROM jdk/node base     [reused]      FROM slim runtime     [reused]
 COPY dependency files  [reused]      COPY config/users     [reused]
 RUN  install deps      [reused]             |
 COPY source            [REBUILT] <-- first miss
 RUN  compile/bundle    [REBUILT] --> COPY --from=build     [REBUILT]

Backend and platform engineers gain the most from this ordering, because they rebuild images many times a day in local loops and CI.

+--------------------------------+      +-------------------------------+
| BUILD STAGE (jdk / node)       |      | RUNTIME STAGE (slim)          |
+--------------------------------+      +-------------------------------+
| [=] FROM jdk/node base         |      | [=] FROM slim runtime         |
|        |                       |      |        |                      |
|        v                       |      |        v                      |
| [=] COPY dependency manifests  |      | [=] COPY config / add user    |
|        |                       |      |        |                      |
|        v                       |      |        v                      |
| [=] RUN  install deps          |      | [R] COPY --from=build         |
|        |                       |      |        ^                      |
|        v                       |      +--------|----------------------+
| [R] COPY source   <-- 1st miss |               |
|        |                       |               |
|        v                       |               |
| [R] RUN  compile / bundle -----+---------------+
+--------------------------------+   built artifacts (jar / dist)

[=] reused from cache        [R] rebuilt on a code-only change
Cache key: parent layer + instruction text (+ file checksums for COPY/ADD)
The first miss changes the parent of every later layer in that stage.
Only the runtime stage's layers ship in the final image.

On a code-only change, the base and dependency layers come from cache, while the source COPY misses and forces the compile step and the runtime stage's COPY --from to rebuild.

How should you order layers in a Node.js Dockerfile?

In a Node.js Dockerfile, the dependency manifest should reach the image before the source code does. Copy package.json and the lockfile (package-lock.json, yarn.lock, or pnpm-lock.yaml) on their own, then run a lockfile-strict install: npm ci, yarn install --frozen-lockfile (or --immutable on newer Yarn), or pnpm install --frozen-lockfile. Strict mode matters for caching as well as reproducibility. If the lockfile and manifest disagree, the build fails instead of quietly resolving new versions, so a cached install layer always matches what the lockfile describes.

Only after the install do you copy the source and run the build. When you edit a route handler, the cache misses at that source COPY step, but the expensive install above it is reused. The common mistake is putting COPY . . before the install. Every file in the build context then feeds into that layer's cache key, so a one-line code change invalidates the install and forces a full dependency download on every build.

The build stage needs devDependencies such as TypeScript, bundlers, and test tooling, but the runtime does not. Add a separate stage that either runs npm prune --omit=dev against the built tree or starts fresh from the manifests and runs npm ci --omit=dev. Older npm releases use --production for this. Reinstalling from scratch is cleaner and gets its own cache layer keyed only on the manifests.

The final stage starts from a slim Node base and uses COPY --from to bring in only dist/ and the production node_modules. Source files, compilers, and the package-manager cache stay behind, which reduces both image size and attack surface.

# syntax=docker/dockerfile:1

# ---- build: full install including devDependencies ----
FROM node:20-slim AS build
WORKDIR /app
# Manifests first: this layer's cache key covers only these two files
COPY package.json package-lock.json ./
# Lockfile-strict install; reused until the manifests change
RUN npm ci
# Source comes after the install, so code edits miss the cache only from here down
COPY . .
RUN npm run build

# ---- prod-deps: production-only node_modules from a clean install ----
FROM node:20-slim AS prod-deps
WORKDIR /app
COPY package.json package-lock.json ./
# Separate cache layer keyed on the manifests; skips devDependencies
RUN npm ci --omit=dev && npm cache clean --force

# ---- runtime: only built output and production dependencies ----
FROM node:20-slim
ENV NODE_ENV=production
WORKDIR /app
COPY --from=prod-deps /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
COPY package.json ./
# Run as the unprivileged user that ships with the official Node images
USER node
CMD ["node", "dist/server.js"]

# Anti-pattern for contrast, do NOT do this:
#   COPY . .
#   RUN npm ci
# Any file change in the build context invalidates the install layer.

A three-stage Node Dockerfile copies the manifests before npm ci so the dependency layer stays cached across code edits, reinstalls production-only dependencies in a separate stage, and ships just dist/ and the production node_modules in a slim runtime image.

How should you order layers for Maven and Gradle builds?

Java builds follow the same principle, but the files that define dependencies differ by tool. For Maven, copy pom.xml (and any .mvn/ directory) on its own. For Gradle, copy settings.gradle, build.gradle (or the Kotlin DSL equivalents), gradle.properties, the gradlew script, and the gradle/ wrapper directory. Then resolve dependencies in a separate RUN step. Maven's dependency:go-offline goal is the usual choice. Gradle has no direct equivalent, so teams often run a task such as dependencies. Only after that step do you copy src/ and compile with a full JDK image. Most commits touch only source files, so the slow download layer stays cached.

Offline resolution is incomplete. Some plugins, plugin dependencies, and dynamically resolved artifacts are fetched only when the real build runs. Treat the pre-fetch layer as an optimization rather than a guarantee. Expect the compile step to download some artifacts, and don't run it in offline mode unless you have verified that it works.

The runtime image benefits from the same ordering. A fat jar is a single blob: change one class and the whole artifact becomes a new layer. Instead, extract the jar in the build stage and COPY its parts into the runtime stage in separate layers, ordered from least to most frequently changed:

  1. Third-party dependencies
  2. Snapshot dependencies
  3. Resources
  4. Application classes

Spring Boot's layered jar support is one well-known way to do this. Its jar mode extracts these groups into separate directories for you.

The final stage should start from a slim JRE base, not a JDK. Compilers and build tools have no place in production.

# ---- Build stage: full JDK + Maven ----
FROM maven:3.9-eclipse-temurin-21 AS build
WORKDIR /src

# Copy only the dependency descriptors first so this layer survives source edits
COPY .mvn/ .mvn/
COPY pom.xml .

# Pre-fetch dependencies. Some plugins/artifacts may still download during package.
RUN mvn -B dependency:go-offline

# Source changes invalidate only the layers from here down
COPY src/ src/
RUN mvn -B package -DskipTests

# Explode the Spring Boot fat jar into layer directories
# (layertools mode; Boot 3.3+ also offers -Djarmode=tools)
RUN cp target/*.jar app.jar \
 && java -Djarmode=layertools -jar app.jar extract --destination extracted

# ---- Runtime stage: slim JRE, no compiler or build tools ----
FROM eclipse-temurin:21-jre
WORKDIR /app

# Least to most frequently changed. Boot's default 'application' layer
# holds both resources and classes; split them via custom layers config if needed.
COPY --from=build /src/extracted/dependencies/ ./
COPY --from=build /src/extracted/spring-boot-loader/ ./
COPY --from=build /src/extracted/snapshot-dependencies/ ./
COPY --from=build /src/extracted/application/ ./

# Launcher class for Spring Boot 3.2+; older versions use org.springframework.boot.loader.JarLauncher
ENTRYPOINT ["java", "org.springframework.boot.loader.launch.JarLauncher"]

A Maven multi-stage Dockerfile that caches dependency resolution separately from source compilation and then copies Spring Boot's extracted jar layers into a slim JRE image, ordered from least to most frequently changed.

Which supporting tools keep the cache effective: .dockerignore, cache mounts, and CI cache export

A .dockerignore file controls what reaches the build cache as well as how big the build context is. COPY . . checksums every file it copies, so a new log file, a locally rebuilt node_modules, a fresh target/ or build/ directory, or a new commit in .git invalidates that layer and every layer after it. Excluding those paths means only real source changes affect the checksum. Excluding .env and other local config files also keeps credentials out of the context. Without that exclusion, a broad COPY would write them into an image layer.

BuildKit cache mounts (RUN --mount=type=cache,target=...) solve a different problem. Point one at the npm cache, ~/.m2, or ~/.gradle. When a lockfile or pom.xml change invalidates the dependency layer, the install step reruns but reuses artifacts it has already downloaded instead of fetching them all again. The mount's contents are never written into the image, and they are not part of an exported build cache by default.

This distinction matters on ephemeral CI runners, which start with an empty local cache. Export the layer cache to a registry or another supported backend after each build, and import it before the next one (--cache-to and --cache-from on docker buildx build). For multi-stage builds, use max mode so that layers from builder stages are exported too, not just layers in the final image. Cache mounts live in the builder's local storage, so a fresh runner starts with them empty unless you persist that storage separately.

Mechanism Scope Persistence What it speeds up
Layer cache One builder instance Until pruned or the builder is discarded Skipping unchanged steps entirely
Cache mount One builder instance Survives layer invalidation, but not a fresh runner Re-downloads inside a step that must rerun
Exported remote cache Any builder with access to the backend As long as the backend keeps it Skipping unchanged steps on new runners
#!/usr/bin/env bash
set -euo pipefail

# 1. Keep irrelevant churn and local secrets out of the build context,
#    so they cannot change the checksum of COPY . . or end up in a layer.
cat > .dockerignore <<'EOF'
node_modules
target
build
dist
.git
*.log
.env
.env.*
EOF

# 2. The Dockerfile's dependency step uses a cache mount, for example:
#      COPY package.json package-lock.json ./
#      RUN --mount=type=cache,target=/root/.npm npm ci
#    For Maven, mount target=/root/.m2 instead. For Gradle, mount target=/root/.gradle.
#    The mount lives only in this builder's local storage. It is not exported below.

# 3. On an ephemeral runner, the default docker driver may not support
#    registry cache export, so use a container-based builder.
docker buildx create --name ci-builder --driver docker-container --use

# Import last run's layer cache, then export this run's cache.
# mode=max also exports layers from builder stages, not just the final image.
CACHE_REF=registry.example.com/team/orders-service:buildcache
docker buildx build \
  --cache-from type=registry,ref="$CACHE_REF" \
  --cache-to type=registry,ref="$CACHE_REF",mode=max \
  --tag registry.example.com/team/orders-service:"${GIT_SHA:-dev}" \
  --push \
  .

A CI build script that trims the build context with .dockerignore, relies on a cache mount for dependency downloads, and imports and exports the multi-stage layer cache through a registry so a fresh runner can skip unchanged steps.

How much engineering time can correct layer order save?

Illustrative estimate (assumed numbers, not a benchmark). Assume a service where resolving and downloading dependencies takes 4 minutes (T_deps) and compiling source takes 1 minute (T_src). A team of six engineers each runs 10 image builds a day, and CI runs 40 more, for 100 builds a day (N).

With bad ordering, the source is copied before dependencies are installed, so every code-only commit reruns both steps. With good ordering, only the compile step reruns.

Scenario Bad ordering Good ordering
One code-only build 5 min 1 min
One build with a manifest or lockfile change 5 min 5 min
Daily total, 100 code-only builds 500 min 100 min
Weekly total, 5 working days 2,500 min 500 min

The saving per day is N × (1 − p) × T_deps, where p is the fraction of builds that change a dependency manifest. At p = 0 that is 400 minutes a day. The cache key for the dependency layer is the manifest file's content, so any change to it invalidates the whole layer. That includes a one-line edit to package-lock.json, pom.xml, or a Gradle file, and an automated transitive bump. If bots push such changes on 10% of builds, the saving drops to 360 minutes a day, or about 30 hours a week.

Part of that saving is engineer waiting time and part is CI runner time, so price them separately. Against the saving, count the maintenance cost: the manifest COPY lines must be updated whenever someone adds a module or workspace. If they are not, the dependency layer either misses files or silently stops caching.

When should you avoid fine-grained layering and slim runtime images?

Fine-grained layering is a design you have to maintain. Every new config file, lockfile, or generated source forces a decision about which layer it belongs in. A COPY placed above the dependency install, or a broad COPY . . added early during a quick fix, brings back cache misses without any error. The build still succeeds and only gets slower, so the regression can go unnoticed for weeks.

Splitting too far also has a cost. Each layer adds metadata, a separate download, and extraction work on every node that pulls the image. Storage drivers also impose practical limits on layer depth. Merge layers that always change together, such as two config files edited in the same commits, because separating them gains nothing.

Slim and distroless runtime bases remove the shell, package manager, and tools like curl. That shrinks the attack surface, but it also removes your usual way to inspect a failing container. Plan for this upfront with a debug image variant or an ephemeral debug container, not during an incident.

Cache mounts can hide nondeterminism. A build that passes only because a warm mount already holds an artifact may fail on a clean runner. Remote cache exports bring their own network transfer, storage cost, and eviction behavior to manage. A large export can take longer than the rebuild it replaces.

A plain, linear Dockerfile is often the better choice in two cases:

  • Rarely rebuilt services. The cache is cold or evicted by the next build anyway.
  • High dependency churn. If the lockfile changes in most commits, the dependency layer rebuilds regardless of where you put it.

What are the alternatives to a hand-written multi-stage Dockerfile, such as Jib?

Jib is a Maven and Gradle plugin that builds a container image straight from your project's build model, with no Dockerfile and no Docker daemon required when pushing directly to a registry. By default it splits the image into separate layers for dependencies, snapshot dependencies, resources, and compiled classes, so a typical code change only rebuilds the small classes layer. That is the same caching benefit you get from careful layer ordering by hand. Jib also fixes file timestamps and image metadata by default. The same inputs therefore produce the same image digest, which helps with deduplication in the registry and with provenance checks.

The trade-off is that Jib cannot execute arbitrary build steps. If you need to install OS packages, native libraries, or certificates, you must bake them into a custom base image and maintain that image separately.

Spring Boot layered jars take a middle path. The jar records layer boundaries, and you extract them inside a multi-stage Dockerfile. You keep full Dockerfile control and get sensible layer splits without writing them yourself.

Approach Flexibility OS packages / native setup Build-tool coupling Mixed Java + Node
Hand-written multi-stage Full Yes, via RUN None One pattern for both
Spring Boot layered jar High Yes Spring Boot only Java side only
Jib Low Only through the base image Maven/Gradle plugin Java only

Choose Jib for plain JVM services where the base image covers runtime needs. Use layered jars for Spring Boot apps that need system setup. Use hand-written multi-stage Dockerfiles when one platform team supports both Java and Node and wants a single, consistent build convention.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to docker multi-stage build layer caching, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Changing a shared variable is one edit and one review instead of editing every service's .env by hand.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.