What is a Layer

A layer is a set of filesystem changes — files added, modified, or deleted — relative to the layer below it. Each layer is stored as a compressed tar archive identified by its SHA256 digest. A container image is an ordered stack of layers.

How it works

Every Dockerfile instruction that modifies the filesystem creates a new layer. FROM ubuntu:22.04 is the base layer. RUN apt-get install nginx creates a layer containing the new files. COPY app.js /app/ creates a layer with that single file.

Layers are immutable and read-only. When a running container modifies a file, the change goes to a writable layer on top — the image layers are never altered. Deleting a file from a lower layer creates a "whiteout" marker in the upper layer that hides the file without removing it from the lower layer's tarball.

Docker caches layers during builds. If an instruction and all preceding layers are unchanged, the cached layer is reused. When a layer changes, all subsequent layers are invalidated and rebuilt. This is why Dockerfiles put rarely-changing instructions (OS packages) before frequently-changing ones (application code).

Why it matters

Layers make container builds and distribution efficient. Building an application after a one-line code change rebuilds only the layer containing that change — not the entire image. Pulling an image downloads only the layers not already cached locally. Multiple images sharing the same base layers store them only once on disk.

See How Container Images Work for the full layer architecture.