8.1.1.3 Layer Deletion Behavior
A focused guide to Layer Deletion Behavior, connecting core concepts with practical Docker and container operations.
Layer deletion behavior describes how deleting a file that originates from a read-only image layer is actually recorded — not by removing it from that underlying layer (which is immutable), but by adding a special marker file in the container's writable layer indicating that file should be treated as deleted in the unified view.
Why a File Can't Actually Be Removed From a Read-Only Layer
Image layers are immutable once built; a container cannot modify or remove content from them directly, even when an application inside the container issues what appears to be an ordinary file deletion.
docker exec myapp rm /app/config-template.yaml
docker diff myapp
D /app/config-template.yaml
The D here reflects this deletion as recorded in the container's writable layer — the underlying image layer containing the original file remains completely unmodified.
The Whiteout File Mechanism
Internally, this kind of deletion is implemented through a "whiteout" marker file written into the writable layer, signaling to the union filesystem that this particular path should be hidden from the merged view, even though the original file still physically exists in a lower, read-only layer.
docker exec myapp ls /app/config-template.yaml
This correctly reports the file as not existing, reflecting the whiteout marker's effect on the unified view, despite the original file's continued presence in the underlying image layer.
Why This Matters for Understanding Image Size
Because the original file remains in the image's read-only layer regardless of any later deletion recorded in a container, deleting a large file within a running container does not reduce the underlying image's actual size at all.
docker images myapp
This size reflects the full, original image content, unaffected by deletions recorded only within a specific container's writable layer.
Why Understanding Layer Deletion Behavior Matters
Recognizing that file deletion within a container is implemented as a marker in the writable layer, rather than an actual removal from the underlying image, clarifies both why deleted files still occupy space in the original image and why this behavior is fundamentally different from deleting a file on an ordinary, non-layered filesystem.