← All notes

Answer: When building with Docker, a layer is reused from the build cache if the instruction and the files it depends on haven't changed since it was previously built. Reusing layers from the cache speeds up the build process because Docker doesn't have to rebuild the layer again. (S2)

How invalidation spreads

• Each instruction in a Dockerfile translates to a layer in your final image. (S1)
• Whenever a layer changes, that layer will need to be re-built. (S1)
• For example, after a change to a source file, the COPY command will have to run again; in other words, Docker will invalidate the cache for this layer. (S1)
• Once a layer changes, then all downstream layers need to be rebuilt as well. (S1)

Ways to use the cache well

• Putting the steps in your Dockerfile into a logical order can help you avoid unnecessary cache invalidation. (S2)
• Keeping the context as small as possible reduces the amount of data that needs to be sent to the builder, and reduces the likelihood of cache invalidation. (S2)
• Bind mounts let you mount a file or directory from the host machine into the build container, which can help you avoid unnecessary layers in the image. (S2)
• Cache mounts let you specify a persistent package cache to be used during builds, so even if you rebuild a layer, you only download new or changed packages. (S2)

Claims

• id: C1 claim: Each Dockerfile instruction becomes a layer. source: S1 evidence: "Each instruction in this Dockerfile translates to a layer in your final image."
• id: C2 claim: A changed layer invalidates all downstream layers. source: S1 evidence: "Once a layer changes, then all downstream layers need to be rebuilt as well."
• id: C3 claim: Reusing cached layers speeds up builds. source: S2 evidence: "Reusing the cache between builds can drastically speed up the build process and reduce cost."
• id: C4 claim: Cache mounts provide a persistent package cache during builds. source: S2 evidence: "Cache mounts let you specify a persistent package cache to be used during builds."

Sources

• [S1] Docker build cache. Docker Docs. https://docs.docker.com/build/cache/ . License: Docker docs, Apache-2.0 (github.com/docker/docs; https://github.com/docker/docs/blob/main/LICENSE); Docker name and logo are trademarks of Docker Inc and are not licensed. Accessed 2026-11-04.
• [S2] Optimize cache usage in builds. Docker Docs. https://docs.docker.com/build/cache/optimize/ . License: Docker docs, Apache-2.0 (github.com/docker/docs; https://github.com/docker/docs/blob/main/LICENSE); Docker name and logo are trademarks of Docker Inc and are not licensed. Accessed 2026-11-04.

License: this note is CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Summary by iinventedlight (AI-assisted).

@misc{iil_note_2yb6d0rz,
  author = {{iinventedlight}},
  title = {{Docker build cache: layers and invalidation}},
  howpublished = {iinventedlight Library},
  year = {2026},
  date = {2026-11-04},
  url = {https://iinventedlight.com/library/notes/docker-build-cache/},
  note = {Permanent ID iil:note:2yb6d0rz. License: CC-BY-4.0.},
}

Markdown

Spotted a mistake? Use the MCP feedback tool or email hello@iinventedlight.com.

For language models and agents: start at /llms.txt. This page in Markdown: /library/notes/docker-build-cache.md.