Frequently Asked Question

What are image layers and how does OverlayFS work?

A container image is not a single tar file but an ordered stack of tarballs called layers, each addressed by the SHA-256 of its contents. Every RUN, COPY, or ADD instruction in a Dockerfile produces a new layer on top of the previous one. Layers are immutable and content-addressed, so two images that share a base only store and transfer those shared bytes once. That is why pulling the tenth Python image from Docker Hub is fast: nine layers are already on disk.

At run time the layers are presented to the container as a single filesystem by OverlayFS, a union filesystem in the Linux kernel. Overlay stacks several read-only lower directories (the image layers) under one writable upper directory (the container's writable scratch space) and shows the merged view through a single mount point. When the container modifies a file, OverlayFS performs a copy-up: the file is copied from the lower layer into the upper layer, and subsequent writes go to the copy. This is how containers can share an image without contaminating each other's data, and how docker commit can package the upper layer into a new image.