A Bind Mount Hides Existing Container Files; It Does Not Merge with Them

[kasenur]

A common misconception about container bind mounts is that mounting a host directory over a container directory combines the contents of both locations. It does not. The mount replaces the directory’s visible view for as long as the mount exists.

Suppose an image contains these files:

/app/config/default.yaml
/app/config/schema.json

The container is then started with a host directory mounted at /app/config:

docker run --mount type=bind,src=/srv/config,dst=/app/config example

If /srv/config contains only production.yaml, the container sees:

It does not also see default.yaml or schema.json. Those image files have not been deleted, copied, or overwritten. They are merely obscured by the mount.

This behavior comes from Linux mount semantics rather than a container-specific merge algorithm. A mount attaches one filesystem tree at a mount point. Path lookup beneath that point proceeds through the mounted tree, so the directory entries from the underlying image layer are no longer reachable through their original paths.

That distinction explains a frequent failure mode: an application works when launched directly from its image, then fails after a configuration directory is mounted. The operator expected to override one file, but mounting the directory hid every image-provided file under that path.

A bind mount also differs from the image’s layered filesystem. Image layers can contribute files to a combined container root filesystem, but a bind mount is applied afterward at a particular path. It does not become another union layer whose entries are merged with the directory underneath.

If only one file should be replaced, mount that file instead of its parent directory:

--mount type=bind,src=/srv/config/production.yaml,dst=/app/config/default.yaml,readonly \