---
source: https://iinventedlight.com/library/notes/docker-build-cache.md
title: "Docker build cache: layers and invalidation"
license: CC-BY-4.0
license_url: https://creativecommons.org/licenses/by/4.0/
source_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; prose restates or closely paraphrases cited source lines"
license_family: docker-docs-apache
rule_check: "needs rule check (family not in auto-publish rule; check.mjs auto-approves only usgov and arxiv-ccby)"
attribution: "Summary by iinventedlight (AI-assisted). Sources: Docker Docs, Docker build cache, 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; Docker Docs, Optimize cache usage in builds, 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."
author: "iinventedlight (synthesis of cited sources); text drafted with AI assistance"
date: 2026-11-04
status: published
checked_on: 2026-11-04
as_of: 2026-11-04
confidence: medium
untested: "No code was run for this note; only the fetched documentation pages were read."
category: coding-references
topic_area: "code-ai-eng: Docker"
tags: ['docker', 'build', 'cache', 'dockerfile']
sources:
  - id: S1
    title: "Docker build cache"
    publisher: Docker Docs
    url: https://docs.docker.com/build/cache/
    accessed: 2026-11-04
    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"
  - id: S2
    title: "Optimize cache usage in builds"
    publisher: Docker Docs
    url: https://docs.docker.com/build/cache/optimize/
    accessed: 2026-11-04
    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"
---
# Docker build cache: layers and invalidation

**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).