8.1.1 Container Write Layer

A container's write layer (its writable layer) is the single layer, created fresh and empty at container creation, where every filesystem modification made during that specific container's running life is actually stored, kept entirely separate from the underlying image's own read-only layers.

Where New and Modified Files Actually Go

Any file created, modified, or deleted within a running container is reflected exclusively within this writable layer, never altering the underlying image layers themselves.

docker run -d --name myapp myapp:1.0
docker exec myapp sh -c "echo 'test' > /tmp/newfile.txt"
docker diff myapp

A /tmp/newfile.txt

This confirms the new file exists specifically in this container's own writable layer, with the underlying image remaining completely unaffected.

Why Multiple Containers Don't Interfere With Each Other

Because each container receives its own independent writable layer, identical changes made within two separate containers created from the same image remain entirely separate from each other.

docker run -d --name container-a myapp:1.0
docker run -d --name container-b myapp:1.0
docker exec container-a sh -c "echo 'a' > /tmp/marker.txt"
docker exec container-b cat /tmp/marker.txt

This fails, since container-b's own writable layer has no knowledge of the file created within container-a's separate writable layer.

What Happens to This Layer When the Container Is Removed

The writable layer is deleted entirely when its container is removed, meaning any data stored only there — and not in a separately managed volume — is permanently lost at that point.

docker rm -f myapp

Why Understanding the Write Layer Matters

A clear understanding of the writable layer's role — capturing all of a specific container's own filesystem changes, kept separate from the image and from every other container — is essential for correctly reasoning about data persistence, and for recognizing why genuinely important data needs a volume rather than relying on this layer alone.