Build Cache

Efficient use of Docker’s build cache can dramatically speed up your image builds. Docker creates a cache layer for each instruction in your Dockerfile. When you rebuild the image, Docker reuses layers whose instructions and contexts haven’t changed, avoiding redundant work.

How Docker’s Build Cache Works

FROM ubuntu
RUN apt-get update
RUN apt-get install -y python python3-pip
RUN pip3 install flask
COPY app.py /opt/source-code
ENTRYPOINT ["flask", "run"]

• Each RUN, COPY, or ADD instruction produces a layer.
• After a successful build, layers are stored in the local cache.
• On subsequent builds, Docker compares:
  1. The instruction itself.
  2. Any files referenced by COPY/ADD.
• If both match the cached layer, Docker reuses it.
• Any change invalidates that layer and all subsequent layers, triggering a rebuild from that point.

Cache Invalidation Example

Changing the pip install command:

RUN pip3 install flask flask-mysql

Invalidates the pip3 install layer and everything that follows—earlier layers remain cached. Similarly, updating app.py in:

COPY app.py /opt/source-code

busts the cache from that layer onward.

Cache Busting with Combined Instructions

Separating apt-get update and apt-get install can lead to stale package lists:

RUN apt-get update
RUN apt-get install -y python python3-pip python-dev

Instead, combine them:

RUN apt-get update && \
    apt-get install -y \
      python \
      python-dev \
      python3-pip

• Forces an update immediately before installation.
• Lists packages alphabetically and on separate lines for readability.

Version Pinning

Pinning package versions ensures consistent builds across environments:

RUN apt-get update && \
    apt-get install -y \
      python \
      python-dev \
      python3-pip=20.0.2

Optimizing Instruction Order

Place instructions that change least frequently at the top of your Dockerfile. This maximizes cache reuse.

Example: Optimal Order

FROM ubuntu

# 1. Infrequently changed – cached once
RUN apt-get update && \
    apt-get install -y \
      python \
      python-dev \
      python3-pip=20.0.2

# 2. Dependencies – rebuild when you add/remove libs
RUN pip3 install flask flask-mysql

# 3. Code – fastest iteration on changes
COPY app.py /opt/source-code

ENTRYPOINT ["flask", "run"]

By contrast, placing COPY app.py first forces Docker to rerun all subsequent layers on every code update, significantly slowing builds.

Further Reading

• Dockerfile Best Practices
• Docker Build Cache Documentation