Layer Caching

LEVEL 0

The Problem

You change one line of code and rebuild your image. Docker reinstalls all dependencies. Why? Your dependencies didn’t change!

Or the opposite: You rebuild without any changes, and Docker says “Using cache” for everything. How does it know?

Understanding caching is essential for fast builds.

LEVEL 2

The Mechanics — How Caching Works

The Mechanics

Cache Decision for Each Layer

For each instruction, Docker asks:

Is this instruction identical to before?
Are all previous layers from cache?
For COPY/ADD: Have the source files changed?

If all answers are “yes (unchanged)”, use cache. Otherwise, rebuild.

Cache Invalidation Cascades

FROM python:3.11-slim      # ✓ Cache (image unchanged)
WORKDIR /app               # ✓ Cache (instruction unchanged)
COPY requirements.txt .    # ✗ Miss! (file changed)
RUN pip install ...        # ✗ Miss! (previous layer changed)
COPY . .                   # ✗ Miss! (previous layer changed)
CMD ["python", "app.py"]   # ✗ Miss! (previous layer changed)

One cache miss invalidates all subsequent layers.

LEVEL 3

Strategic Layer Ordering

Bad: Code before dependencies

COPY . .                           # Miss every time code changes
RUN pip install -r requirements.txt  # Reinstall every time!

Good: Dependencies before code

COPY requirements.txt .            # Only miss if deps change
RUN pip install -r requirements.txt  # Cached if deps unchanged
COPY . .                           # Code changes don't affect above

LEVEL 4

Cache Busting and Control

Force No Cache

docker build --no-cache -t myapp .

Ignores all cache, rebuilds everything.

Selective Cache Busting (ARG trick)

ARG CACHEBUST=1
RUN apt-get update  # Changes when ARG changes

docker build --build-arg CACHEBUST=$(date +%s) -t myapp .

BuildKit Cache Mounts

Modern Docker (BuildKit) can cache package manager data:

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