Add docs for image mounts (--mount type=image) #25486
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,208 @@ | ||
| --- | ||
| description: Using image mounts | ||
| title: Image mounts | ||
| weight: 40 | ||
| keywords: storage, mounts, image mounts, image mount | ||
| --- | ||
|
|
||
| [Volumes](volumes.md), [bind mounts](bind-mounts.md), and [tmpfs mounts](tmpfs.md) | ||
| all give a container a place to read and write data. An image mount is | ||
| different: instead of mounting a directory or a memory-backed filesystem, it | ||
| mounts the contents of another image into the container. | ||
|
|
||
| When you use an image mount, the filesystem of a second image is mounted into | ||
| the container at a path you choose. The container can read the files from that | ||
| image alongside its own filesystem, without those files being part of the | ||
| container's own image. This is useful when you want to bring the tools or assets | ||
| from one image into a container that's running a different image. | ||
|
|
||
| Image mounts are read-only. The mounted image is never modified, and the | ||
| container can't write to the mount. | ||
|
|
||
| > [!NOTE] | ||
| > Image mounts require the [containerd image store](containerd.md). | ||
|
|
||
| ## When to use image mounts | ||
|
|
||
| Image mounts are appropriate for the following types of use case: | ||
|
|
||
| - Debugging a minimal or hardened image that doesn't include a shell or common | ||
| utilities. You can mount a tool-rich image, such as `busybox`, into the | ||
| running container's namespace and run those tools without changing the | ||
| original image. For a worked example, see | ||
| [Debug with Docker Hardened Images](/manuals/dhi/troubleshoot.md). | ||
|
|
||
| - Sharing read-only assets, such as datasets, models, or static content, that | ||
| are distributed as an image and consumed by containers running a different | ||
| image. | ||
|
|
||
| - Keeping application images small by packaging optional tooling in a separate | ||
| image and mounting it only when needed. | ||
|
|
||
| ## Mounting over existing data | ||
|
|
||
| If you mount an image into a directory in the container in which files or | ||
| directories exist, the pre-existing files are obscured by the mount. This is | ||
| similar to if you were to save files into `/mnt` on a Linux host, and then | ||
| mounted a USB drive into `/mnt`. The contents of `/mnt` would be obscured by the | ||
| contents of the USB drive until the USB drive was unmounted. | ||
|
|
||
| With containers, there's no straightforward way of removing a mount to reveal | ||
| the obscured files again. Your best option is to recreate the container without | ||
| the mount. | ||
|
|
||
| ## Considerations and constraints | ||
|
|
||
| - Image mounts are always read-only. The container can't modify the mounted | ||
| image, and changes aren't persisted anywhere. | ||
|
|
||
| - The source image must already exist in the daemon's image store. Docker | ||
| doesn't pull the source image automatically when you create the mount. If the | ||
| image isn't present, the command fails: | ||
|
|
||
| ```console | ||
| $ docker run --mount type=image,source=busybox:musl,destination=/dbg alpine | ||
| docker: Error response from daemon: No such image: busybox:musl | ||
| ``` | ||
|
|
||
| Pull the image first with `docker pull`, then create the mount. | ||
|
|
||
| - Image mounts require the [containerd image store](containerd.md). They aren't | ||
| available when the daemon uses the classic storage drivers. | ||
|
|
||
| - You can only create an image mount with the `--mount` flag. There is no | ||
| `--volume` (`-v`) equivalent. | ||
|
|
||
| - Running an executable from a mounted image requires a compatible runtime in | ||
| the container. A dynamically linked binary only runs if the container provides | ||
| a matching dynamic linker and shared libraries. For example, a glibc-based | ||
| binary fails in a musl-based image such as Alpine. Statically linked binaries, | ||
| or mounting only data from an image, avoid this constraint. | ||
|
|
||
| ## Syntax | ||
|
|
||
| To mount an image with the `docker run` command, use the `--mount` flag with | ||
| `type=image`. | ||
|
|
||
| ```console | ||
| $ docker run --mount type=image,src=<image-reference>,dst=<container-path> | ||
| ``` | ||
|
|
||
| The `--mount` flag consists of multiple key-value pairs, separated by commas and | ||
| each consisting of a `<key>=<value>` tuple. The order of the keys isn't | ||
| significant. | ||
|
|
||
| ```console | ||
| $ docker run --mount type=image,src=<image-reference>,dst=<container-path>[,<key>=<value>...] | ||
| ``` | ||
|
|
||
| ### Options for --mount | ||
|
|
||
| Valid options for `--mount type=image` include: | ||
|
|
||
| | Option | Description | | ||
| | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | | ||
| | `source`, `src` | The reference of the image to mount, for example `busybox` or `busybox:musl`. The image must exist locally. | | ||
| | `destination`, `dst`, `target` | The path where the image is mounted in the container. Must be an absolute path. | | ||
| | `image-subpath` | Path inside the source image to mount instead of the image root. See [Mount a subpath of an image](#mount-a-subpath-of-an-image). | | ||
|
|
||
| ```console {title="Example"} | ||
| $ docker run --mount type=image,src=busybox,dst=/dbg,image-subpath=bin | ||
| ``` | ||
|
|
||
| ## Use an image mount in a container | ||
|
|
||
| The following example runs an Alpine container and mounts the `busybox:musl` | ||
| image at `/dbg`. Pull the source image first, since Docker doesn't pull it for | ||
| you when creating the mount. This example uses the musl-based BusyBox image so | ||
| its binaries are compatible with the musl-based Alpine container. | ||
|
|
||
| ```console | ||
| $ docker pull busybox:musl | ||
| $ docker run -d \ | ||
| -it \ | ||
| --name imgtest \ | ||
| --mount type=image,source=busybox:musl,destination=/dbg \ | ||
| alpine:latest | ||
| ``` | ||
|
|
||
| The container can now read the BusyBox tools from `/dbg` while running the Alpine | ||
| image: | ||
|
|
||
| ```console | ||
| $ docker exec imgtest /dbg/bin/echo "hello from busybox" | ||
| hello from busybox | ||
| ``` | ||
|
|
||
| Verify that the mount is an `image` mount by looking in the `Mounts` section of | ||
| the `docker inspect` output: | ||
|
|
||
| ```console | ||
| $ docker inspect imgtest --format '{{ json .Mounts }}' | ||
| [{"Type":"image","Name":"busybox:musl","Source":"/var/lib/docker/rootfs/overlayfs/...","Destination":"/dbg","Mode":"","RW":false,"Propagation":"rprivate"}] | ||
|
dvdksn marked this conversation as resolved.
Contributor
There was a problem hiding this comment. [LOW] The example output shows: Image mounts require the containerd image store. The actual source path on a containerd-backed daemon may differ from the Since the value is truncated with |
||
| ``` | ||
|
|
||
| This shows that the mount is an `image` mount, that its source is the | ||
| `busybox:musl` image, and that it's read-only (`"RW":false`). | ||
|
|
||
| Stop and remove the container: | ||
|
|
||
| ```console | ||
| $ docker container rm -fv imgtest | ||
| ``` | ||
|
|
||
| ## Mount a subpath of an image | ||
|
|
||
| Use the `image-subpath` option to mount a specific directory from the source | ||
| image instead of its root. For example, to mount only the `bin` directory of the | ||
| `busybox` image at `/tools`: | ||
|
|
||
| ```console | ||
| $ docker run -d \ | ||
| -it \ | ||
| --name imgtest \ | ||
| --mount type=image,source=busybox,destination=/tools,image-subpath=bin \ | ||
| alpine:latest | ||
| ``` | ||
|
|
||
| The container sees the contents of the image's `bin` directory at `/tools`. | ||
|
|
||
| ## Use an image mount with Docker Compose | ||
|
|
||
| A single Docker Compose service with an image mount looks like this: | ||
|
|
||
| ```yaml | ||
| services: | ||
| app: | ||
| image: alpine:latest | ||
| volumes: | ||
| - type: image | ||
| source: busybox | ||
| target: /dbg | ||
| ``` | ||
|
|
||
| To mount a subpath of the image, use the `subpath` option under `image`: | ||
|
|
||
| ```yaml | ||
| services: | ||
| app: | ||
| image: alpine:latest | ||
| volumes: | ||
| - type: image | ||
| source: busybox | ||
| target: /tools | ||
| image: | ||
| subpath: bin | ||
| ``` | ||
|
|
||
| The `image.subpath` option is available in Docker Compose version 2.35.0 and | ||
| later. For more information about using mounts of the `image` type with Compose, | ||
| see the | ||
| [Compose reference on the volume attribute](/reference/compose-file/services.md#volumes). | ||
|
|
||
| ## Next steps | ||
|
|
||
| - Learn about [volumes](./volumes.md). | ||
| - Learn about [bind mounts](./bind-mounts.md). | ||
| - Learn about [tmpfs mounts](./tmpfs.md). | ||
| - Learn about [storage drivers](/engine/storage/drivers/). | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[HIGH]
docker runsyntax examples are missing the required container image argumentBoth syntax examples omit the container image positional argument that
docker runrequires:$ docker run --mount type=image,src=<image-reference>,dst=<container-path>Without an image name at the end, this command will fail. Since these are presented as runnable
consoleexamples (with a$prompt), users will copy-paste and get an error. A corrected form would be:$ docker run --mount type=image,src=<image-reference>,dst=<container-path> <container-image>The same fix applies to the extended form on line 96.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That example is ambiguous though so maybe using something like:
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Great suggestion! Using
<mounted-image>and<runtime-image>makes the distinction much clearer. The current<image-reference>and<container-path>labeling doesn't help users understand that there are two images involved: the one being mounted as a data source, and the one that's actually running as the container.Your proposal removes that ambiguity nicely — it's immediately obvious which image is which.