3.1.2.2 Image Layer Reuse

Image layer reuse is the practice of referencing an already-existing layer — whether from a previous build of the same image or from an entirely different image — instead of recreating identical content, which both speeds up builds and reduces the total storage and transfer required across many related images.

Reuse Within a Single Project's Builds

When rebuilding an image after a change, Docker reuses every layer up to the point where the Dockerfile or its build context actually differs from the previous build, only recreating layers from that point onward.

docker build -t myapp:1.0 .
echo "# comment" >> app.py
docker build -t myapp:1.1 .

If the dependency installation layer in this Dockerfile comes before the COPY of app.py, the second build reuses that dependency layer entirely, since nothing affecting it changed.

Reuse Across Different Images

Two entirely different images that happen to share a common base, or that both run an identical early instruction, can reuse that shared layer rather than each storing or rebuilding it separately.

docker pull python:3.12-slim
docker build -t app-a -f Dockerfile.a .
docker build -t app-b -f Dockerfile.b .

If both Dockerfile.a and Dockerfile.b start FROM python:3.12-slim, that base layer is reused by both images without being duplicated.

Reuse Across Hosts

Because layers are identified by content digest, a layer already pulled on one host for one purpose can be reused locally for a different image that happens to reference the same layer, without needing to download it again.

docker pull node:20-alpine
docker pull myapp:1.0

If myapp:1.0 happens to share its base layers with the already-pulled node:20-alpine image, those shared layers are not downloaded a second time.

Why Layer Reuse Matters

Layer reuse is what keeps incremental builds fast and keeps storage and network usage proportional to what is genuinely unique across an organization's images, rather than to the total combined size of every image considered independently.