8.1.2.3 File Copy Up
A focused guide to File Copy Up, connecting core concepts with practical Docker and container operations.
File copy-up is the specific operation a union filesystem performs the first time a file originating from a read-only layer is modified — copying that file's content up into the writable layer — which is the actual underlying mechanism implementing copy-on-write behavior for individual files.
The Copy-Up Operation in Detail
Before a modification can actually be applied to a file from a read-only layer, the storage driver first copies that file's entire content into the writable layer, then applies the requested modification to this newly copied version.
docker exec myapp sh -c "sed -i 's/old/new/' /app/config.yaml"
Before this sed command's modification actually takes effect, the entire config.yaml file is first copied up into the writable layer, with the substitution then applied to this copied version.
Why Copy-Up Happens at the File Level, Not the Layer Level
This operation copies only the specific file being modified, not the entire layer it originates from — modifying one file doesn't trigger copying every other file in that same layer.
docker exec myapp sh -c "echo 'change' >> /app/file-a.txt"
docker diff myapp
This reveals only file-a.txt as changed, confirming that copy-up operates at the individual file level rather than copying an entire layer's worth of content.
Why This Operation Can Be Costly for Large Files
Because the entire file must be copied before any modification can be applied, even a tiny change to a very large file incurs the cost of copying that file's complete content.
docker exec myapp sh -c "echo 'x' >> /app/large-dataset.csv"
If large-dataset.csv is several gigabytes, this single, tiny append operation still requires copying the entire multi-gigabyte file before the addition can actually be applied.
Why Understanding File Copy-Up Matters
A clear understanding of this specific mechanism explains the otherwise potentially surprising performance characteristic of modifying large files inherited from an image's read-only layers, and helps inform decisions about when a volume (which avoids this layered filesystem mechanism entirely) would be more appropriate for files expected to undergo frequent or substantial modification.