Skip to main content
Docker·7 min read

Docker Build Cache — How Layer Caching Works and How to Keep It

Master the Docker build cache: how layer caching works, what invalidates a layer, ordering instructions for maximum cache hits, .dockerignore, BuildKit cache mounts with RUN --mount=type=cache, and when to use --no-cache.

DT

DevOps Engineer & Technical Writer

The Problem

A one-character change to your source code triggers a five-minute rebuild that reinstalls every dependency from scratch. That is almost always a cache problem. Docker builds images layer by layer and caches each layer, but a single misordered instruction can invalidate everything below it. Understanding what invalidates a layer and in what order to put instructions is the difference between a 2-second rebuild and a 5-minute one.

BUILD CACHE — HIT vs MISS AND HOW INVALIDATION CASCADES ONLY SOURCE CHANGED FROM node:20-alpine CACHE HIT COPY package*.json ./ CACHE HIT RUN npm ci CACHE HIT COPY . . (source changed) CACHE MISS → rebuild RUN npm run build REBUILT (below miss) DEPENDENCY CHANGED EARLY FROM node:20-alpine CACHE HIT COPY package*.json ./ (changed) CACHE MISS RUN npm ci INVALIDATED COPY . . INVALIDATED RUN npm run build INVALIDATED A miss invalidates every layer below it — order from least to most frequently changing

How Layer Caching Works

Each Dockerfile instruction produces a layer. Before executing an instruction, Docker checks whether it already has a cached layer for the exact same instruction built on the exact same parent layer. If yes, it reuses the cache (a cache hit). If anything differs, it rebuilds that layer and — crucially — every layer below it (a cache miss that cascades).

The cache key for a layer depends on:

  • The instruction text itself (RUN npm ci, COPY . ., etc.)
  • The parent layer's identity
  • For COPY/ADD, a checksum of the files being copied

What Invalidates the Cache

A layer is invalidated when any of its inputs change:

ChangeEffect
Edit the instruction textThat layer + everything below rebuilds
A file in a <code class="inline-code">COPY</code>/<code class="inline-code">ADD</code> set changesThat <code class="inline-code">COPY</code> layer + everything below rebuilds
The base image is updatedEntire build rebuilds
A build <code class="inline-code">ARG</code> used by the layer changesThat layer + below rebuilds
An earlier layer missedAll later layers rebuild, even if unchanged

The last row is the big one: cache misses cascade downward, never upward. That is the whole reason ordering matters.

Order Instructions for Cache Hits

Put the things that rarely change near the top and the things that change constantly near the bottom.

Slow: source copied before dependencies install

FROM node:20-alpine

WORKDIR /app

COPY . . # ANY source change invalidates everything below

RUN npm ci # reinstalls dependencies on every code change

RUN npm run build

Fast: dependency manifests first

FROM node:20-alpine

WORKDIR /app

# Changes rarely → stays cached across most builds

COPY package.json package-lock.json ./

RUN npm ci

# Changes often → only these layers rebuild on a code edit

COPY . .

RUN npm run build

Copying package.json and the lockfile before the rest of the source means npm ci only re-runs when your dependencies actually change — not on every edit to a .js file.

Use a .dockerignore

Without .dockerignore, COPY . . sends your entire working tree to the build context — including .git, node_modules, logs, and local env files. Those files change constantly and bust the COPY cache even when your real source did not.

# .dockerignore

.git

node_modules

dist

*.log

.env

.env.*

coverage

Dockerfile

docker-compose.yml

Smaller, stable context means faster uploads and far more reliable cache hits.

BuildKit Cache Mounts

Ordering keeps layers cached across builds, but it does not persist a package manager's own download cache. BuildKit cache mounts do. A RUN --mount=type=cache directory survives between builds without becoming part of the image.

# syntax=docker/dockerfile:1

FROM node:20-alpine

WORKDIR /app

COPY package.json package-lock.json ./

RUN --mount=type=cache,target=/root/.npm \

npm ci

COPY . .

RUN npm run build

Even when the npm ci layer is invalidated, npm pulls packages from the mounted cache instead of the network. The same pattern works for other ecosystems:

# Go

RUN --mount=type=cache,target=/go/pkg/mod go mod download

# Python / pip

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

# apt

RUN --mount=type=cache,target=/var/cache/apt \

apt-get update && apt-get install -y --no-install-recommends build-essential

Enable BuildKit (default in recent Docker, or set it explicitly):

DOCKER_BUILDKIT=1 docker build -t myapp .

When to Bypass the Cache

Sometimes you want a clean build — for example to pick up a new patch of a base image, or to debug a flaky build.

# Ignore all cache for this build

docker build --no-cache -t myapp .

# Force a fresh base image, then build normally

docker build --pull -t myapp .

Use --no-cache sparingly in CI; it throws away every optimization and makes builds slow for everyone.

Common Mistakes to Avoid

  • COPY . . before installing dependencies. This is the number one cache killer. Copy manifests first, install, then copy the rest.
  • No .dockerignore. Noisy context (git history, node_modules, logs) busts the COPY cache on unrelated changes.
  • Combining unrelated steps into one RUN. A single giant RUN cannot be partially cached; split along change-frequency lines.
  • Using --no-cache as a habit. It hides real ordering problems and wastes CI minutes. Fix the Dockerfile instead.
  • Expecting cache mounts without BuildKit. RUN --mount=type=cache needs the # syntax=docker/dockerfile:1 header and BuildKit enabled, or it is silently ignored (older engines error out).

FAQ

Why does changing one source file reinstall all my dependencies?

Because your COPY . . runs before RUN npm install. Any source change invalidates the COPY layer and every layer below it, including dependency installation. Copy package.json and the lockfile first, install, then copy the rest of the source so dependency layers stay cached.

What is the difference between layer cache and a BuildKit cache mount?

Layer cache reuses a whole built layer when its inputs are unchanged. A cache mount persists a directory (like ~/.npm or the Go module cache) across builds without baking it into the image, so even a rebuilt layer can skip re-downloading packages. They complement each other.

Does .dockerignore affect the build cache?

Yes. Files excluded by .dockerignore are not sent to the build context, so they cannot trigger a COPY/ADD cache miss. Ignoring volatile files like .git, logs, and node_modules keeps the context stable and your COPY layers cached.

When should I use --no-cache?

Use --no-cache when you need a guaranteed-fresh build — for example to pull in security patches from an updated base image or to rule out a stale cache while debugging. Avoid it as a default in CI because it discards all caching and makes every build slow.