4.3.1.4 Cache Layer Reuse

Cache layer reuse is the practical benefit Docker's build cache provides whenever a layer's required inputs match a previous build exactly, allowing the daemon to skip re-executing an instruction entirely and instead reuse the already-existing layer it previously produced.

Recognizing a Reusable Layer

For each instruction, Docker checks whether a layer already exists that was produced by the same instruction, applied to the same starting state — if so, that existing layer is reused rather than the instruction being executed again.

FROM python:3.12-slim
RUN apt-get update && apt-get install -y curl
COPY requirements.txt .
RUN pip install -r requirements.txt

docker build -t myapp .
docker build -t myapp .

The second build, with nothing changed, reuses every single layer from the first, completing almost instantly.

Reuse Across Different Images Sharing Common Layers

Layer reuse is not limited to rebuilding the same image — any two images that happen to share an identical instruction applied to an identical starting state reuse the same underlying layer, even if they are otherwise unrelated images.

FROM python:3.12-slim
RUN apt-get update && apt-get install -y curl

Two separate Dockerfiles both starting this way, built on the same host, can share this exact layer rather than each rebuilding it independently.

Observing Reuse During a Build

Build output explicitly indicates when a step's result was reused from cache rather than newly executed, making it straightforward to confirm reuse is actually happening as expected.

docker build --progress=plain -t myapp . 2>&1 | grep -i cache

Why Cache Layer Reuse Matters

Layer reuse is the underlying mechanism that makes Docker's caching system actually save time in practice — recognizing exactly when it does and does not apply is essential for both troubleshooting unexpectedly slow builds and for deliberately structuring a Dockerfile to take full advantage of it.

docker build -t myapp .