Image Layers and the Build Cache

Each instruction in a Dockerfile, the file of build steps for an image, produces a layer: a record of the files that instruction added, changed or removed, stored on its own. docker build keeps those layers as a build cache and reuses one whenever it can, instead of running the instruction again.

A build that took twelve seconds the first time takes under one the second time, and nothing about your machine got faster. The work was not done again.

Before running an instruction, the builder asks one question: has it already run this exact instruction on top of this exact layer? For COPY, "exact" includes the contents of the files being copied. If the answer is yes, it reuses the stored layer and skips the work. If not, it runs the instruction and stores a new layer.

RUN npm ci, for instance, produces a layer that holds the packages it installed and nothing else, and COPY . . produces a layer that holds your project's files. A layer is never the whole filesystem, only the difference one instruction made.

Two consequences follow. A layer is the unit of caching, so whatever makes a layer differ decides how long your builds take. A layer is also the unit of storage, so old layers are what slowly fills the disk.

So a slow build is usually a cache that could not be used, and the question to ask is which layer changed, and why.