Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 37 ยท Pods and Volumes

Volumes and Bind Mounts in Podman

Keep data beyond a container's life with Podman volumes, bind mounts and tmpfs: create and inspect volumes, use -v and --mount, read-only mounts, SELinux flags and cleanup.

Everything a container writes to its own file system lives in the writable layer, and it disappears when the container is removed. For a web server that is fine; for a database it is a disaster. Volumes and bind mounts put data somewhere that outlives the container, and let several containers or you and a container share files.

Podman offers three kinds of mount, and most day-to-day decisions are choosing between them:

Kind Where the data lives Managed by Best for
Named volume a folder in Podman's storage Podman databases, application state, anything the container owns
Bind mount a folder or file you choose on the host you source code, config files, files you edit on the host
tmpfs memory the kernel scratch data, secrets in transit, speed

Named volumes

Terminal
podman volume create appdata
podman volume ls
podman volume inspect appdata

podman run -d --name db \
  -v appdata:/var/lib/postgresql/data \
  -e POSTGRES_PASSWORD=example \
  docker.io/library/postgres:17

The part before the colon is the volume name; the part after is the path inside the container. If the volume does not exist, Podman creates it. In rootless mode its files are stored in ~/.local/share/containers/storage/volumes/appdata/_data; podman volume inspect prints the exact Mountpoint. You do not normally edit files there by hand. Remove the container and start another one with the same -v appdata:..., and the data is still there.

Handy volume commands:

Terminal
podman volume create --label project=shop appdata
podman volume ls --filter label=project=shop
podman volume rm appdata               # fails if a container uses it (add --force to remove those too)
podman volume prune                    # remove volumes no container uses (asks first)
podman volume exists appdata && echo yes

First-use initialization: when a named volume is empty and is mounted onto a path that already has files in the image, Podman copies those files into the volume once. That is how a database image starts with a ready directory structure. A bind mount does the opposite: it hides whatever the image had at that path.

Anonymous volumes appear when an image declares VOLUME /data and you do not name one: Podman creates a volume with a random name. They are easy to forget and accumulate; use podman volume ls and podman rm --volumes to keep them in check, and prefer naming your volumes.

Bind mounts

Terminal
mkdir -p ~/site
echo '<h1>Hello from the host</h1>' > ~/site/index.html

podman run -d --name web -p 8080:80 \
  -v ~/site:/usr/share/nginx/html:ro,Z \
  docker.io/library/nginx:alpine

If the first part is a path (starting with /, ./, ../ or ~), -v makes a bind mount. If it is a plain word, it is a volume name. With a bind mount, edits you make on the host appear in the container immediately, and the other way around.

Podman is strict about missing host paths: it will not create the folder for you, and gives an error instead (create it first with mkdir -p). That is helpful, because a typo does not silently create an empty directory.

Options after the second colon

Options go in a comma-separated list at the end:

Option Meaning
ro read-only inside the container
rw read-write (default)
z SELinux: relabel as shared, usable by several containers
Z SELinux: relabel as private to this container
U change the owner of the files to the container user (UID and GID)
O overlay mount: the container sees the files but its changes go to a temporary layer, not to the host
noexec, nosuid, nodev mount flags that block running programs, setuid files or device nodes

ro is the safest default for configuration and code. O is nice for build tools: the container can write temporary files without modifying your source. The z/Z flags matter on SELinux systems and must not be used on system folders (SELinux, Seccomp and Capabilities). U is covered in the next lesson, because ownership is the usual rootless headache.

Here is a stand-in that parses a -v argument into parts, including the "volume or bind mount" decision. It is JavaScript, not Podman.

JS Stand-in: parse -v arguments

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The --mount form

--mount uses explicit key=value pairs, so it is easier to read and harder to get wrong:

Terminal
podman run --rm \
  --mount type=volume,src=appdata,dst=/data \
  --mount type=bind,src=/home/alice/site,dst=/srv,ro=true,relabel=private \
  --mount type=tmpfs,dst=/tmp,tmpfs-size=64m \
  docker.io/library/alpine:latest df -h /data /srv /tmp

type is volume, bind, tmpfs, image (mount an image's file system read-only, useful for sharing data) or devpts. For a bind mount the keys include src/source, dst/destination/target, ro/readonly, relabel (shared or private), idmap and bind-propagation. Both syntaxes work; scripts and Quadlet files benefit from the explicit one.

tmpfs

A tmpfs lives in memory, is fast, and disappears with the container. It is a safe place for temporary files and works well with a read-only root:

Terminal
podman run -d --read-only --tmpfs /tmp:rw,size=64m,mode=1777 docker.io/library/nginx:alpine

Memory used by a tmpfs counts toward the container's memory limit.

Sharing a volume between containers

Many containers may mount the same volume. Typical patterns: a writer and a reader (an app writes reports, a web server serves them), or an init container that fills a volume and an app that uses it. Keep in mind that Podman does not lock files: the programs must coordinate, and two databases must never share the same data directory.

Terminal
podman run --rm -v reports:/out docker.io/library/alpine:latest sh -c 'date > /out/last-run.txt'
podman run --rm -v reports:/in:ro docker.io/library/alpine:latest cat /in/last-run.txt

The second container sees the file the first one wrote, read-only.

Choosing quickly

  • Database or app state: named volume.
  • Source code or config you edit on the host: bind mount, usually ro.
  • Temporary files: tmpfs.
  • Need to share with another container: a named volume both mount.
  • Want to look at the data from the host in rootless mode? Bind mounts are easier, because volume ownership uses mapped IDs (next lesson).
JS Stand-in: which mount should I use?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does -v appdata:/var/lib/data create when appdata is a plain word?

    A source that does not look like a path is a volume name. Use ./appdata for a folder.
  2. 2. What happens when you bind-mount a host path that does not exist?

    Podman refuses missing bind sources, which catches typos. Create the folder first.
  3. 3. Which option makes a mount read-only?

    ro makes the mount read-only. Z is an SELinux label, O is an overlay, and U changes ownership.
  4. 4. What is special about an empty named volume mounted onto a path that has files in the image?

    Named volumes are initialized from the image contents on first use; bind mounts only hide them.
  5. 5. Which mount type is best for a database's data directory?

    A named volume survives container removal and is managed by Podman.

Summary

  • Named volumes, bind mounts and tmpfs store data outside the container's writable layer.
  • -v name:/path makes a volume, -v ./path:/path a bind mount, and --mount type=... is the explicit form.
  • Podman will not auto-create missing bind sources; options like ro, z, Z, U and O refine the mount.
  • Named volumes are initialized from the image's files; bind mounts hide them.
  • Use named volumes for state, bind mounts for files you edit, and tmpfs for scratch space.
  • Volumes are managed with podman volume create, ls, inspect, rm and prune.

Next: Volume Permissions, Ownership and Backups