Skip to content

engine: add bind-create-src mount option #24140

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
dvdksn wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

engine: add bind-create-src mount option #24140

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion content/get-started/docker-concepts/running-containers/sharing-local-files.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ Here's a way to use `docker run` to start a container using a bind mount and map
$ docker run -v /HOST/PATH:/CONTAINER/PATH -it nginx
```

The `--mount` flag offers more advanced features and granular control, making it suitable for complex mount scenarios or production deployments. If you use `--mount` to bind-mount a file or directory that doesn't yet exist on the Docker host, the `docker run` command doesn't automatically create it for you but generates an error.
The `--mount` flag offers more advanced features and granular control, making it suitable for complex mount scenarios or production deployments. By default, if you use `--mount` to bind-mount a file or directory that doesn't yet exist on the Docker host, the `docker run` command doesn't automatically create it for you but generates an error.

```console
$ docker run --mount type=bind,source=/HOST/PATH,target=/CONTAINER/PATH,readonly nginx
Expand Down
22 changes: 15 additions & 7 deletions content/manuals/engine/storage/bind-mounts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,14 +87,21 @@ If you use `--volume` to bind-mount a file or directory that does not yet
exist on the Docker host, Docker automatically creates the directory on the
host for you. It's always created as a directory.

`--mount` does not automatically create a directory if the specified mount
By default, `--mount` does not automatically create a directory if the specified mount
path does not exist on the host. Instead, it produces an error:

```console
$ docker run --mount type=bind,src=/dev/noexist,dst=/mnt/foo alpine
docker: Error response from daemon: invalid mount config for type "bind": bind source path does not exist: /dev/noexist.
```

You can use the `bind-create-src` option to automatically create the source directory
on the host if it doesn't exist:
Copy link
Contributor

@github-actions github-actions bot Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Terminology inconsistency between "source directory" and "source path"

The text here uses "source directory" but the error message directly above uses "bind source path does not exist" and the table below uses "source path" in "the source path doesn't exist on the daemon".

For terminology consistency per STYLE.md, this should use "source path" to match error messages and table descriptions. This helps users since they'll encounter "source path" in error messages.

Suggestion: Change "automatically create the source directory" to "automatically create the source path"


```console
$ docker run --mount type=bind,src=/dev/mydir,dst=/mnt/foo,bind-create-src alpine
Copy link
Contributor

@github-actions github-actions bot Feb 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Misleading example using /dev directory

The example uses /dev/mydir as the source path. The /dev directory is a special system directory reserved for device files, and users should never create regular directories there.

Per STYLE.md code example guidance ("Use realistic text"), this example should use a realistic user directory that users might actually create and bind-mount.

Suggestion: Change /dev/mydir to something like /home/user/mydir or /tmp/mydir

Note: The /dev/noexist example above is fine since it's demonstrating an error condition, not showing what users should do.

```

### Options for --mount

The `--mount` flag consists of multiple key-value pairs, separated by commas
Expand All @@ -107,12 +114,13 @@ $ docker run --mount type=bind,src=<host-path>,dst=<container-path>[,<key>=<valu

Valid options for `--mount type=bind` include:

| Option | Description |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| `source`, `src` | The location of the file or directory on the host. This can be an absolute or relative path. |
| `destination`, `dst`, `target` | The path where the file or directory is mounted in the container. Must be an absolute path. |
| `readonly`, `ro` | If present, causes the bind mount to be [mounted into the container as read-only](#use-a-read-only-bind-mount). |
| `bind-propagation` | If present, changes the [bind propagation](#configure-bind-propagation). |
| Option | Description |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source`, `src` | The location of the file or directory on the host. This can be an absolute or relative path. |
| `destination`, `dst`, `target` | The path where the file or directory is mounted in the container. Must be an absolute path. |
| `readonly`, `ro` | If present, causes the bind mount to be [mounted into the container as read-only](#use-a-read-only-bind-mount). |
| `bind-propagation` | If present, changes the [bind propagation](#configure-bind-propagation). |
| `bind-create-src` | Automatically creates the source directory on the host if it doesn't exist. By default, `--mount` produces an error if the source path doesn't exist on the daemon. |

```console {title="Example"}
$ docker run --mount type=bind,src=.,dst=/project,ro,bind-propagation=rshared
Expand Down