Skip to content
Tutorials Center
My learning

Topics

Lesson 47 of 111 ยท Data and Volumes

Bind Mounts

Share a host folder with a container using bind mounts: -v and --mount syntax, live code editing, read-only mounts, file ownership, and Windows and macOS path notes.

A bind mount takes a file or folder that already exists on your computer and makes it appear at a path inside a container. There is no copy: both sides see the same files, so a change you make in your editor shows up in the container instantly, and a file the container writes lands on your disk. That is exactly what you want while developing: edit code on the host, let the program inside the container pick it up.

Volumes are managed by Docker and hidden away; a bind mount is the opposite. You choose the host path, you own the files, and every tool on your machine can open them. This lesson shows both command-line syntaxes, a live-editing workflow, read-only mounts, the permission problems that bite everyone once, and the path rules on Windows and macOS.

What a bind mount really is

When Docker starts a container, it builds the container's filesystem from the image layers plus a writable layer. A bind mount is laid on top of one directory of that filesystem, like plugging a USB stick into a folder. Whatever the image had at that path is hidden for as long as the mount is there.

TEXT
  Host                               Container
  ----                               ---------
  ~/project/site/                    /usr/share/nginx/html/
     index.html   <==== same files ====>   index.html
     style.css                              style.css

  (image's original /usr/share/nginx/html is hidden underneath)

Three consequences follow, and they explain most surprises:

  • The host path must make sense on the host. The path is resolved by the Docker daemon, not by the container. With a remote daemon, -v ./site:/app points at a folder on the remote machine.
  • The mount hides what was there. If the image shipped files at the target path, you will not see them while the mount is active.
  • The container can change your files. Unless you mount read-only, a rm -rf inside the container deletes real files on your disk.

Two syntaxes: -v and --mount

Docker accepts two forms. -v (or --volume) is short and has been around forever. --mount is longer, explicit and easier to read in scripts.

Terminal
# Short form: host-path:container-path[:options]
docker run -v "$PWD/site:/usr/share/nginx/html:ro" nginx:alpine

# Long form: comma-separated key=value pairs
docker run --mount type=bind,src="$PWD/site",dst=/usr/share/nginx/html,readonly nginx:alpine
Concept -v --mount
Host path first field source= or src=
Container path second field destination=, dst= or target=
Read-only :ro readonly (or ro)
Kind of mount guessed from the first field type=bind, type=volume or type=tmpfs

The guessing in -v is the source of a classic mistake. If the first field starts with /, ./ or a drive letter, it is a path and you get a bind mount. If it is a plain word, it is a volume name:

Terminal
docker run -v data:/data alpine       # named volume called "data"
docker run -v ./data:/data alpine     # bind mount of the folder ./data

Forgetting the ./ silently gives you a volume instead of your folder. With --mount you always spell out type=, so there is nothing to guess.

Relative paths after -v work in recent Docker versions (./site), but older guides insist on absolute paths such as $(pwd)/site. Absolute paths work everywhere, so they are the safe choice in scripts shared with other people.

A live-editing workflow

Create a tiny website on the host and serve it from a container:

CONSOLE
$ mkdir site
$ echo '<h1>Hello from the host</h1>' > site/index.html
$ docker run -d --name web -p 127.0.0.1:8080:80 -v "$PWD/site:/usr/share/nginx/html:ro" nginx:alpine
e71457e97212
$ curl -s 127.0.0.1:8080
<h1>Hello from the host</h1>

Now edit the file on the host, without touching the container:

CONSOLE
$ echo '<h1>Edited on the host</h1>' > site/index.html
$ curl -s 127.0.0.1:8080
<h1>Edited on the host</h1>

No rebuild, no restart, no docker cp. This is the heart of bind-mount development: your editor, linter and Git all work on normal files, and the container is only the runtime. Frameworks with a file watcher (Vite, Next.js dev server, Flask's reloader, nodemon) pick up the change and reload by themselves.

You can see how the mount was configured with docker inspect:

CONSOLE
$ docker inspect -f '{{json .Mounts}}' web
[{"Type":"bind","Source":"/home/you/site","Destination":"/usr/share/nginx/html","Mode":"ro","RW":false,"Propagation":"rprivate"}]

Type is bind, RW is false because of :ro, and Propagation is rprivate. The last field only matters for mounts inside mounts and you can ignore it almost always.

Read-only mounts

Add :ro (or readonly) whenever the container only needs to read the files: web content, configuration files, certificates, source code for a compiler. A compromised or buggy program then cannot damage the host folder.

CONSOLE
$ docker exec web sh -c 'echo x > /usr/share/nginx/html/new.txt'
sh: can't create /usr/share/nginx/html/new.txt: Read-only file system

Two details are worth knowing. The read-only flag belongs to this mount, not to the host folder: you can still edit the files on the host. And it protects only the mounted path; the rest of the container filesystem stays writable unless you also use --read-only (see Users and Permissions).

Mounting a single file

You can mount one file instead of a folder, which is handy for configuration:

CONSOLE
$ docker run --rm -v "$PWD/site/index.html:/x.html" alpine cat /x.html
<h1>Edited on the host</h1>

There is a trap. Many editors save a file by writing a new file and renaming it over the old one. The rename gives the file a new identity, but the bind mount still points at the old one, so the container keeps seeing stale content until you restart it. If a single-file mount "does not update", this is almost always the reason. Mount the parent folder instead when you edit live.

When the host path does not exist

The two syntaxes disagree about a missing source. Historically, -v creates the missing path as an empty directory, owned by root, which is how you end up with a mysterious folder named like your config file. --mount is strict on a Linux Docker Engine and fails with bind source path does not exist, so typos are caught immediately.

Docker Desktop is more forgiving. We tried both on a Windows machine and both created the folder:

CONSOLE
$ docker run --rm --mount type=bind,src=/c/work/nonexistent,dst=/data alpine ls /data
$ ls -d /c/work/nonexistent
/c/work/nonexistent/

Do not rely on this: develop on Desktop, deploy on Linux, and write paths that exist on both. With --mount, a missing path is an error on Linux, and that is the behavior you want.

Permissions and file ownership

Files in a bind mount keep their real owner and mode on the host. Inside the container, the numbers (UID and GID) are what matter, not user names. A process running as root inside the container can write anywhere. A process running as node (UID 1000 in the official image) can write only what UID 1000 may write.

On Linux, this produces two opposite problems:

  1. Container creates root-owned files on your disk. Run a build as root in a container and your dist/ folder is owned by root. You then need sudo to delete it.
  2. Container cannot write to your folder. A non-root user inside the container has a different UID from your host user, so writes fail with "Permission denied".

The usual fix is to run the container with your own IDs:

CONSOLE
$ id -u
1000
$ docker run --rm --user "$(id -u):$(id -g)" -v "$PWD/out:/out" alpine sh -c 'id; echo built > /out/result.txt; ls -ln /out'
uid=1000 gid=1000 groups=1000
total 0
-rw-r--r--    1 1000     1000             6 Oct 23 14:40 result.txt

The process runs as UID 1000, so on a Linux host the new file belongs to the user with that UID: you. If you need a fixed user inside the image, build with matching IDs or use a chown step in an entrypoint; see Users and Permissions for the options.

On Docker Desktop for Windows and macOS the mount goes through a file-sharing layer that hides most ownership problems: files appear owned by root inside the container, whatever they are on the host.

CONSOLE
$ docker run --rm -w /w -v "$PWD/site:/w" alpine sh -c 'echo hi > made.txt; ls -l made.txt; id'
-rw-r--r--    1 root     root             3 Oct 23 14:33 made.txt
uid=0(root) gid=0(root) groups=0(root)

The file belongs to the Windows user on the host, but root inside. That convenience can hide a bug that appears only on a Linux server, so test non-root setups there too.

On Linux machines with SELinux (Fedora, RHEL, Rocky), a bind mount can fail with "Permission denied" even when the owner is right. Add :z (shared label) or :Z (private label) to the mount, for example -v ./data:/data:Z. Never use these on system folders such as /home or /etc: Docker relabels the folder recursively.

Windows and macOS path notes

  • Windows, PowerShell or cmd: use native paths, for example -v C:\Users\you\site:/usr/share/nginx/html, or -v ${PWD}/site:/app in PowerShell. Quote paths that contain spaces.
  • Windows, Git Bash: Git Bash rewrites anything that looks like a Unix path. -v /app:/app may be converted into a Windows path before Docker sees it. Set MSYS_NO_PATHCONV=1 for the command, or start paths with // when it bites.
  • Docker Desktop with WSL 2: keep your project inside the Linux filesystem (~/project in your WSL distribution), not under /mnt/c/.... Files in the Linux filesystem are much faster to read, and file-change notifications work reliably.
  • macOS: Docker Desktop only shares certain folders by default (your home folder). A path outside them fails until you add it under Settings, Resources, File sharing.
  • Both: bind mounts through the file-sharing layer are slower than volumes, especially for folders with tens of thousands of small files such as node_modules.

That last point has a standard solution: bind-mount your source code, but keep heavy generated folders in a volume layered on top.

YAML
# compose.yaml (excerpt)
services:
  app:
    build: .
    volumes:
      - ./src:/app/src            # bind mount: you edit these files
      - node_modules:/app/node_modules   # volume: fast, not visible on the host
volumes:
  node_modules:

Bind mount, volume or tmpfs?

Need Use
Edit code on the host while the container runs Bind mount
Give a container a configuration file or certificates from the host Bind mount, read-only
Database files, uploads, anything that must survive and be portable Volume
Scratch data or secrets that must never touch the disk tmpfs
Production deployment Usually volumes, not host paths

Avoid bind mounts in production unless you have a reason. They tie a container to a specific folder layout on one machine, which makes the same Compose file behave differently from host to host.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. You run docker run -v data:/app alpine expecting to mount your local folder named data. What do you get?

    With -v, a first field that is a plain word is a volume name. Use ./data or an absolute path for a bind mount, or write --mount type=bind,src=... to remove the ambiguity.
  2. 2. What does the :ro suffix on a bind mount do?

    Read-only applies to the container's view of the mount. The host folder itself is unchanged and still editable by you.
  3. 3. You mount a single file with -v and edit it with an editor that saves by renaming a new file over the old one. What usually happens?

    The mount follows the original file, and the rename replaced it with a new one. Mount the parent folder instead of a single file when you edit live.
  4. 4. A container running as root writes build output into a bind-mounted folder on a Linux host. Who owns the new files on the host?

    Ownership is stored as numeric IDs. UID 0 inside the container is root on the Linux host. Run with --user $(id -u):$(id -g) to avoid it.
  5. 5. Why is --mount often preferred over -v in scripts?

    --mount uses named keys (type, src, dst) and reports mistakes such as a missing source. -v guesses the type from the first field and may create a root-owned empty directory.

Summary

  • A bind mount shares a host file or folder with a container; both see the same data, with no copy.
  • Use -v host:container[:ro] for short commands and --mount type=bind,src=...,dst=...,readonly for clarity.
  • With -v, a first field without a path prefix means a named volume, not a folder.
  • Add :ro when the container only needs to read.
  • Mount folders, not single files, if you edit them live.
  • Ownership uses numeric IDs: on Linux, run with --user "$(id -u):$(id -g)"; on SELinux hosts add :z or :Z.
  • On Windows and macOS keep projects in a fast location (inside WSL 2), and put heavy folders like node_modules in a volume.

Next: tmpfs and In-Memory Storage