When working with Docker, a common requirement is to share files between your host machine and a running container. This is especially useful for development, configuration, data persistence, and debugging.
In this guide, we’ll walk through how to mount a host directory into a Docker container, step by step.
📦 What Is a Volume Mount?
Mounting a host directory into a Docker container means mapping a folder from your local machine into the container’s filesystem. This allows:
- Real-time file access and changes
- Persistent data across container restarts
- Configuration injection without rebuilding the image
🧪 Basic Syntax
You can mount a host directory using the -v or --mount flag with docker run.
🔹 Using -v Option
docker run -v /path/on/host:/path/in/container IMAGE_NAME
🔹 Using --mount Option (Recommended)
docker run \
--mount type=bind,source=/path/on/host,target=/path/in/container \
IMAGE_NAME
Both achieve the same result, but --mount provides a clearer, more structured syntax.
🛠 Example: Mounting a Local Directory
Suppose you have a directory on your host at /home/user/data and you want to access it inside your container at /app/data.
docker run -it --rm \
-v /home/user/data:/app/data \
ubuntu \
bash
Inside the container, you’ll find all files from /home/user/data available in /app/data.
⚙ Use Case: Sharing Code for Development
docker run -it \
-v $(pwd):/usr/src/app \
-w /usr/src/app \
node:18 \
node index.js
This mounts your current directory into the container, allowing real-time editing and testing of code.
🧱 Important Considerations
✅ Paths Must Be Absolute
Relative paths will not work reliably. Always use full, absolute paths for both host and container.
🔐 File Permissions
The container may not have the same user permissions as your host. You might need to adjust ownership or use user flags (--user) accordingly.
🔁 Two-Way Sync
Changes made inside the container will reflect on the host — and vice versa.
❗ Troubleshooting Tips
- Permission denied: Ensure the container user has rights to access the host directory.
- Mount not working on Windows/Mac: Make sure file sharing is enabled for your drive in Docker Desktop.
- Empty directory in container: If the container path already exists and isn’t empty, Docker won’t override it unless
:roor proper flags are set.
🔒 Optional Flags
| Flag | Description |
|---|---|
:ro | Mounts the volume read-only |
:rw | Default, read-write access |
--read-only | Mounts the entire container filesystem as read-only, except volumes |
Example:
-v /config:/app/config:ro
📌 Summary
| Action | Command |
|---|---|
| Mount host dir | -v /host/path:/container/path |
| Use structured mount | --mount type=bind,source=/host,path,target=/container/path |
| Read-only mount | Add :ro at the end |
| Verify mounts | docker inspect <container_id> |
🚀 Conclusion
Mounting host directories into Docker containers is a powerful technique to accelerate development, manage configurations, and retain data. Whether you’re building Node.js apps, debugging logs, or persisting database files — volume mounts make containers truly versatile.