# Docker Caching


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

## How Docker build caching works

Docker builds your application in layers, with each instruction in a
Dockerfile creating a new layer. When you rebuild your image, Docker can
reuse unchanged layers from its cache rather than recreating them. This
is one of Docker’s most powerful features for development efficiency.

Think of Docker’s caching mechanism like building a layered cake. If the
bottom layers haven’t changed, Docker won’t bake them again—it simply
reuses those existing layers and only bakes the changed ones on top.

## Our dockerfile design philosophy

Our Dockerfile structure is deliberately organized to maximize cache
efficiency. You might notice that we handle dependencies before copying
your application code:

    # System dependencies first
    COPY .dockerignore setup.sh* ./
    RUN if [ -f ./setup.sh ]; then ... fi

    # Then Python dependencies
    COPY .dockerignore requirements.txt* ./
    RUN if [ -f ./requirements.txt ]; then ... fi

    # Finally, application code
    COPY . .

This isn’t arbitrary—it follows a “least likely to change” to “most
likely to change” progression. System dependencies rarely change, Python
package requirements change occasionally, and your application code
changes frequently during development.

## Why this matters for development speed

When you’re iterating on your application, you typically make frequent
changes to your code while your dependencies remain stable. Because
we’ve structured the Dockerfile to install dependencies first, Docker
can reuse those cached layers and only rebuild the layers containing
your updated code.

Without this approach, even a small code change would trigger a complete
reinstallation of all dependencies—turning a 5-second rebuild into a
5-minute one.

## The real-world impact

Consider a typical development cycle: you change a few lines of code,
rebuild, test, and repeat. With our caching strategy, each rebuild might
take seconds instead of minutes. Over the course of a day, this could
save hours of waiting time.

The most significant performance gain comes from keeping your
requirements.txt and setup.sh files stable. When these files remain
unchanged, Docker can reuse the expensive dependency installation
layers, dramatically reducing build times.

## Trade-offs and considerations

While our approach optimizes for development speed, it does mean that if
you do need to update dependencies, you’ll invalidate several cache
layers. This is an intentional trade-off—we’ve prioritized the more
common workflow (code changes) over the less frequent one (dependency
updates).

Understanding this caching behavior helps you develop more efficiently
and explains why we’ve structured our Docker environment the way we
have.