Docker Bind Mounts (docker run --volume)

The short answer

To mount a local directory into a Docker container (i.e. bind mount), you can use the docker run command combined with the -v option flag (short for --volume) as follows:

$ docker run -v <host_directory>:<container_directory> <image>

Where:

• host\_directory is the absolute or relative path of the bind mount on your local machine.
• container\_directory is the absolute path of the file or directory within the container.
• image is the name of the Docker image the container will be launched from.

For example:

$ docker run -v ./app:/app node-server

The above command mounts the app directory in the current directory into the container at the /app path using the -v flag.

Note that if the specified directory doesn't exist on your local machine, Docker will automatically create it before starting the container.

Also note that the use of relative local paths are only available as of Docker version 23.

If instead you are looking for persistent storage, you can read more about named volumes on the official Docker volumes page.

Easily retrieve this command using Warp’s AI Command Search

If you’re using Warp as your terminal, you can easily retrieve this command using the Warp AI Command Search feature:

‍

Entering docker run volume directory in the AI Command Search will prompt an docker run command that can then quickly be inserted into your shell by doing CMD+ENTER.

The --volume and --mount flags

The --volume and --mount flags are both used to mount a file or a directory into a container and essentially have the same behavior, only with a different syntax.

The --volume flag

The -v (or --volume) flag consists of three fields, separated by colon characters:

$ docker run -v <source>:<destination>:<options> <image>

Where:

• The source field is the path of the file or directory on the host machine.
• The destination field is the path where the file or directory is mounted into the container.
• The options field is a comma separated list of options.

For example:

$ docker run -v ./app:/app:ro alpine

The --mount flag

The --mount flag consists of multiple key-value pairs, separated by commas and each consisting of a key=value tuple:

$ docker run --mount type=<type>,source=<source>,destination=destination>,<options> <image>

Where:

• The type field is the type of the mount, which should be set to bind when using bind mounts.
• The source field is the path of the file or directory on the host machine.
• The destination field is the path where the file or directory is mounted into the container.
• The options field is a comma separated list of options.

For example:

$ docker run -v --mount type=bind,source=./app,destination=/app alpine,readonly

Differences between --volume and --mount

Besides their syntax, the only difference between these flags is their behavior when it comes to creating bind-mounted directories that don't exist.

When using the -v or --volume flag, Docker will automatically create the bind-mounted directory on your local machine if it doesn't exist.

When using the --mount flag, Docker will not create the bind-mounted directory on your local machine if it doesn't exist and generate an error.

You can learn more about bind mounts on the official Docker documentation page.

Mounting files and directories into a container

As of Docker version 23, you can mount a local file or directory into a container using either its relative or absolute path.

Mounting the current directory

To mount the current directory into the container at a specified path, you can use the dot syntax as follows:

$ docker run -v .:/path/to/directory <image>

To mount the current directory at the same path into the container, you can use the command substitution syntax with the pwd command as follows:

$ docker run -v $(pwd):$(pwd) <image>

Note that when using this syntax, Docker will automatically create all the intermediary directories starting from the root in order to preserve the directory structure.

Mounting a file

To mount a single file into a container, you can use the same syntax as for directories:

$ docker run -v /path/to/file:/path/to/file <image>

Using multiple bind mounts

To mount several files or directories into a container, you can repeat the -v flag multiple times as follows:

$ docker run -v ./dir_1:/app/dir_1 -v ./dir_2:/app/dir_2 <image>

Use a read-only bind mounts

By default, any modifications made by a container to the files and directories of a bind mount will be propagated back to the local machine.

To prevent that, you can define a bind mount as read-only, either using the ro option when working with the -v flag:

$ docker run -v ./app:/app:ro alpine

Or the readonly option when working with the --mount flag:

$ docker run --mount type=bind,source=./app,target=/app,readonly alpine

Using bind mounts on Windows

When working with Docker for Windows, there are essentially two ways you can write the paths of the files and directories you want to mount into a container.

You can either use escaped Windows-like paths as follows:

$ docker run -v C:\\Users\\user\\work:/work <image>

Or you can use Unix-like paths as follows:

$ docker run -v //c/Users/user/work:/work <image>

Note that when using the $(pwd) command substitution, you will have to prepend a slash character to this expression in order for it to work:

$ docker run -v /$(pwd):/work <image>