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.
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:
| Change | Effect |
|---|---|
| Edit the instruction text | That layer + everything below rebuilds |
| A file in a <code class="inline-code">COPY</code>/<code class="inline-code">ADD</code> set changes | That <code class="inline-code">COPY</code> layer + everything below rebuilds |
| The base image is updated | Entire build rebuilds |
| A build <code class="inline-code">ARG</code> used by the layer changes | That layer + below rebuilds |
| An earlier layer missed | All 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 theCOPYcache on unrelated changes. - Combining unrelated steps into one
RUN. A single giantRUNcannot be partially cached; split along change-frequency lines. - Using
--no-cacheas a habit. It hides real ordering problems and wastes CI minutes. Fix the Dockerfile instead. - Expecting cache mounts without BuildKit.
RUN --mount=type=cacheneeds the# syntax=docker/dockerfile:1header 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.