3.1.2.3 Image Layer Cache

The image layer cache is the daemon's record of previously built layers, keyed by the instruction and the state it was applied to, which lets a build skip re-executing instructions whose result is already known and unchanged.

How the Cache Decides What to Reuse

For each instruction in a Dockerfile, the daemon checks whether a layer already exists that was produced by the same instruction applied to the same starting state; if so, it reuses that layer directly instead of re-executing the instruction.

FROM node:20-alpine
COPY package*.json ./
RUN npm install
COPY . .
CMD ["node", "server.js"]

docker build -t myapp:1.0 .
docker build -t myapp:1.1 .

If package*.json has not changed between these two builds, the npm install layer is reused from cache, since both the instruction and its input are identical to the previous build.

What Invalidates the Cache

Any change to an instruction's content, or to the files it depends on (in the case of COPY or ADD), invalidates the cache for that instruction and every instruction after it in the Dockerfile, since their starting state has now changed.

echo "console.log('updated')" >> server.js
docker build -t myapp:1.2 .

Because server.js is copied by a COPY instruction that comes after npm install, only that layer and anything after it needs to be rebuilt — the dependency installation layer remains cached.

Explicitly Bypassing the Cache

The cache can be deliberately bypassed, which is useful when a build needs to be forced to re-run every instruction regardless of whether their inputs appear unchanged — for example, to pick up updated packages from a remote source that the build process cannot detect changed.

docker build --no-cache -t myapp:1.0 .

Why Ordering Instructions Carefully Matters

Because cache invalidation cascades from the point of change onward, placing instructions that change infrequently (installing dependencies) before instructions that change frequently (copying application source) maximizes how much of a typical rebuild can be served from cache.

COPY package*.json ./
RUN npm install
COPY . .

Why the Layer Cache Matters

The layer cache is what makes iterative development with Docker practical — without it, every build would re-execute every instruction from scratch, turning what should be a quick rebuild into a slow, full reconstruction every time.