# Mounts and volumes
Share data from your host with containers, create named volumes with better
performance and lifecycle guarantees than bind mounts, and mount temporary,
memory-backed storage with tmpfs.
## Share host data
With the `--volume` option of `container run`, you can share data between the host system and one or more containers, and you can persist data across multiple container runs. Use the volume option to mount a folder on your host to a filesystem path in the container.
This example mounts a folder named `assets` on your Desktop to the directory `/content/assets` in a container:
% ls -l ~/Desktop/assets
total 8
-rw-r--r--@ 1 fido staff 2410 May 13 18:36 link.svg
% container run --volume ${HOME}/Desktop/assets:/content/assets docker.io/python:alpine ls -l /content/assets
total 4
-rw-r--r-- 1 root root 2410 May 14 01:36 link.svg
%
The argument to `--volume` in the example consists of the full pathname for the host folder and the full pathname for the mount point in the container, separated by a colon.
The `--mount` option uses a comma-separated `key=value` syntax to achieve the same result:
% container run --mount source=${HOME}/Desktop/assets,target=/content/assets docker.io/python:alpine ls -l /content/assets
total 4
-rw-r--r-- 1 root root 2410 May 14 01:36 link.svg
%
## Named volumes
Named volumes offer complementary features to bind mounts. Use a named volume when you
don't need to share data with the host filesystem, and you want better I/O performance
than a bind mount provides.
Create a named volume with `container volume create`:
```bash
container volume create foo
```
By default, a volume uses a journaled `ext4` filesystem. Configure the journal mode and
size at creation time with `--opt`:
```bash
# ordered journaling (default)
container volume create --opt journal=ordered myvolume
# writeback journaling with a 64 MiB journal
container volume create --opt journal=writeback:64m myvolume
# full data journaling with an explicit volume size
container volume create --opt journal=journal --opt size=10g myvolume
```
List and remove volumes:
```bash
container volume list
container volume delete foo
```
Show a volume's configuration, including its size and the path to its backing image:
```bash
container volume inspect foo
```
```console
[
{
"configuration" : {
"creationDate" : "2026-08-10T21:39:10Z",
"driver" : "local",
"format" : "ext4",
"labels" : {
},
"name" : "foo",
"options" : {
},
"sizeInBytes" : 549755813888,
"source" : "\/Users\/fido\/Library\/Application Support\/com.apple.container\/volumes\/foo\/volume.img"
},
"id" : "foo"
}
]
```
A volume's image is sparse, so `sizeInBytes` reports the size the volume can grow to —
512 GiB by default — rather than the space it currently occupies on disk.
Remove every volume that has no container referencing it:
```bash
container volume prune
```
> [!WARNING]
> `container volume prune` deletes the volumes and their contents immediately, and the data
> can't be recovered.
Mount a named volume the same way you bind-mount a host directory, using the volume
name as the source:
```bash
container run -it --rm --volume foo:/mnt/foo alpine sh
```
Or with `--mount`:
```bash
container run -it --rm --mount type=volume,source=foo,target=/mnt/foo alpine sh
```
## Anonymous volumes
Using `-v /path` or `--mount type=volume,target=/path` without specifying a source creates
a named volume for you automatically — an anonymous volume. It's named with a bare UUID
(no prefix) and tagged with the `com.apple.container.resource.anonymous` label:
```bash
# Creates an anonymous volume
container run -v /data alpine
```
`container volume list` marks it `anonymous` in the `TYPE` column. For scripting, select it
by its label, since the JSON output has no type field:
```bash
VOL=$(container volume list --format json | jq -r '.[] | select(.configuration.labels["com.apple.container.resource.anonymous"] != null) | .id')
container run -v $VOL:/data alpine
```
> [!NOTE]
> Unlike Docker, anonymous volumes aren't deleted automatically when the container is
> removed with `--rm`. Delete them explicitly:
>
> ```bash
> container volume delete $VOL
> ```
## Tmpfs mounts
A `tmpfs` mount is temporary storage that lives only in the guest VM's memory. When the
container stops, the mount and everything written to it are gone. You can't share a
`tmpfs` mount between containers, unlike a bind mount or a named volume.
Use a `tmpfs` mount when you need high-performance storage and don't need the data to
persist after the container stops.
Use either `--tmpfs` or `--mount type=tmpfs`. Both accept the `size` and `mode` options;
see [Mount options](#mount-options) for the syntax each one takes.
Mount a `tmpfs` filesystem at `/tmpfsmount1` with `--tmpfs`:
```bash
container run --rm --tmpfs /tmpfsmount1 alpine mount -t tmpfs
```
```console
tmpfs on /tmpfsmount1 type tmpfs (rw,relatime)
tmpfs on /dev/shm type tmpfs (rw,nosuid,nodev,noexec,relatime,size=65536k)
tmpfs on /sys/firmware type tmpfs (ro,nosuid,nodev,noexec,relatime)
```
The last two entries are runtime defaults, present in every container. See
[Runtime configuration](./runtime-configuration.md#mask-and-protect-paths-inside-a-container)
for what mounts `/sys/firmware` read-only.
Mount a `tmpfs` filesystem with a 512 MiB size limit using `--mount`:
```bash
container run --rm --mount type=tmpfs,target=/tmpfsmount1,size=512M alpine stat -f /tmpfsmount1
```
```console
File: "/tmpfsmount1"
ID: 89a6eaf01fc1572c Namelen: 255 Type: tmpfs
Block size: 4096
Blocks: Total: 131072 Free: 131071 Available: 131071
Inodes: Total: 142352 Free: 142350
```
131072 blocks × 4096 bytes = 512 MiB, confirming the size limit took effect.
Set the mount's permission bits with `mode` (octal, same as `chmod`):
```bash
container run --rm --mount type=tmpfs,target=/tmpfsmount1,size=512M,mode=1777 alpine stat -c '%a' /tmpfsmount1
```
```console
1777
```
## Mount options
Mount-time options go on `container run` or `container create`, using `--mount`,
`--volume`, or `--tmpfs`. Creation-time options go on `container volume create`, using
`--opt`.
### Options for `--mount`
`--mount` takes comma-separated `key=value` pairs. An unrecognized key is an error.
| Key | Values | Applies to | Description |
|---|---|---|---|
| `type` | `bind` (alias `virtiofs`), `volume`, `tmpfs` | — | The kind of mount to create. Defaults to a bind mount. |
| `source`, `src` | host path, or volume name | bind mounts, named volumes | The host directory to share, or the name of the volume to mount. Omit it for a tmpfs mount, or to get an [anonymous volume](#anonymous-volumes). |
| `destination`, `dst`, `target` | absolute container path | all | Where the mount appears inside the container. |
| `readonly`, `ro` | key only, no value | all | Mount read-only. |
| `size` | for example `512M`, `1G` | tmpfs only | Upper bound on the guest memory the mount can consume. |
| `mode` | octal, for example `1777` | tmpfs only | Permission bits for the mount point, the same as `chmod`. |
### Options for `--volume`
`--volume` uses the colon-separated form `[source:]destination[:options]`, comma-separated
if there is more than one:
```bash
container run --rm --volume foo:/mnt/foo:ro alpine sh
```
| Key | Values | Description |
|---|---|---|
| `ro` | key only, no value | Mount read-only. |
### Options for `--tmpfs`
`--tmpfs` uses the colon-separated form `destination[:options]`, comma-separated if there
is more than one:
```bash
container run --rm --tmpfs /tmpfsmount1:size=64M,mode=1777 alpine sh
```
| Key | Values | Description |
|---|---|---|
| `size` | for example `512M`, `1G` | Upper bound on the guest memory the mount can consume. |
| `mode` | octal, for example `1777` | Permission bits for the mount point, the same as `chmod`. |
### Options for `container volume create`
| Key | Values | Description |
|---|---|---|
| `size` | for example `10g` | Size of the volume's filesystem image, fixed at creation time. |
| `journal` | `ordered` (default), `writeback`, `journal`, each optionally as `:` | The `ext4` journal mode, and optionally the journal size — for example `writeback:64m`. |