Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 37 ยท Pods and Volumes

Volume Permissions, Ownership and Backups

Fix permission denied errors on Podman volumes in rootless mode with :U, keep-id and podman unshare, then back up and restore volumes with export, import and tar.

The most common first complaint about rootless containers is "permission denied" on a volume or bind mount, or files on the host owned by a number such as 100999. These problems all come from one fact you learned in Rootless and User Namespaces: container user IDs are translated into different host IDs. Once you can do that translation in your head, the fixes are short.

This lesson gives a workflow for diagnosing ownership problems, the options that solve them (:U, --userns=keep-id, podman unshare chown), and then shows how to back up and restore volumes, which is the other thing you must be able to do before you trust a volume with real data.

Diagnose first

Ask three questions:

  1. Which user does the process run as inside the container? podman exec NAME id, or check the image documentation (USER in the Containerfile).
  2. Who owns the target path? On the host (for a bind mount) or inside the container with ls -ln (-n shows numbers).
  3. What does that owner mean on the other side of the mapping?

For a default rootless setup with your UID 1000 and range 100000:65536:

Container UID Host UID
0 (root) 1000 (you)
1 100000
70 (postgres in some images) 100069
999 100998
1000 100999

If the process runs as container UID 999 and the folder on the host is owned by you (host UID 1000, which is container UID 0), the process is "someone else" and, with default permissions (755), cannot write. The cure is to make the folder owned by the container user's mapped ID, or to make the process run as you.

Here is a stand-in that checks write access under this mapping. It follows the simplified owner/group/other permission logic and ignores ACLs and capabilities.

JS Stand-in: can the container user write here?

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

No output.

The row with 777 shows why "chmod 777" appears in tutorials and why you should not do it: it works because everyone can write, which also includes every other program on your account.

Fix 1: the :U option

Append U to a volume or bind mount and Podman changes the owner of the content to the user the container runs as, using the mapping, before the container starts:

Terminal
mkdir -p ~/pgdata
podman run -d --name db \
  -v ~/pgdata:/var/lib/postgresql/data:Z,U \
  -e POSTGRES_PASSWORD=example \
  docker.io/library/postgres:17

U is the simplest fix for databases and other images that run as a fixed non-root user. Remember its limit: it changes ownership of the host files, recursively and every time the container starts. Do not use it on a folder you also edit by hand, and never on a large folder shared with other containers that run as different users.

Fix 2: run as yourself with keep-id

For development, where files should stay yours, use --userns=keep-id. Your host UID is also your UID inside the container, and by default the process runs as you:

Terminal
podman run --rm -it --userns=keep-id \
  -v "$PWD:/work:Z" -w /work \
  docker.io/library/node:22-alpine sh -c 'id -u; npm --version; touch built-by-container'
ls -ln built-by-container

The new file belongs to your real UID on the host. It also means no chown is ever needed for your project folder. For a named volume that is used only by one service, :U is better; for a source tree you edit, keep-id is better.

Fix 3: set ownership explicitly with podman unshare

When you need exact control, enter the user namespace and use the container's numbers:

Terminal
podman unshare chown -R 999:999 ~/pgdata       # now owned by container UID 999 (host 100998)
podman unshare ls -ln ~/pgdata
podman unshare chmod 700 ~/pgdata

Inside unshare, you are "container root", so chown works with container IDs, and the files end up with the mapped host owners. Use ls -ln outside to see the host numbers. This approach also fixes the opposite problem: files created by a container that you now cannot delete as yourself. Run podman unshare rm -r ~/pgdata/old to delete them with the right identity.

Named volumes

Named volumes follow the same mapping, but the files live in Podman's own folder. Two points:

  • A named volume that was created and filled by the container itself has the right owner already, because the container user created the files. No fixing needed.
  • To change one on purpose, find its folder with podman volume inspect NAME --format '{{.Mountpoint}}' and use podman unshare chown -R on that path. Prefer :U on the -v option when you use a volume that you filled differently.

A volume can also pin ownership when created: podman volume create --opt o=uid=999,gid=999 ... applies to volume drivers that support these options (for example the local driver with a type), so check what your version supports before depending on it.

Backing up a volume

A volume is a folder, but you should not copy it while a database is writing to it. The safe order is: stop the container (or quiesce the app), copy, start again. Databases also have their own dump tools (pg_dump, mysqldump) which are better for logical backups.

Method 1: podman volume export and import

Terminal
podman stop db
podman volume export appdata --output appdata-2026-11-12.tar
podman start db

# restore into a new volume
podman volume create appdata-restored
podman volume import appdata-restored appdata-2026-11-12.tar

export writes the volume contents as a tar archive and import reads one into an existing volume. The archive keeps ownership as numbers inside the namespace, so it restores correctly for the same container user.

Method 2: a helper container with tar

This works on any version and lets you compress:

Terminal
podman run --rm \
  -v appdata:/data:ro \
  -v "$PWD:/backup:Z" \
  docker.io/library/alpine:latest \
  tar czf /backup/appdata.tgz -C /data .

podman run --rm \
  -v appdata-restored:/data \
  -v "$PWD:/backup:Z,ro" \
  docker.io/library/alpine:latest \
  tar xzf /backup/appdata.tgz -C /data

Mounting the source as :ro guarantees the backup cannot change it. (BusyBox tar in Alpine supports -C and czf.)

Method 3: copy a bind mount with rsync -a or cp -a, after stopping the container. Ownership may show as high numbers, so use podman unshare rsync if you need to keep the mapped identity.

Whichever method you use, test a restore: create a fresh volume, restore, start a container on it, and check the data. A backup you never restored is a hope, not a backup.

Here is a final stand-in that decides which backups to keep with a simple daily/weekly rule. It is plain JavaScript.

JS Stand-in: backup retention

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

No output.

Quick reference for ownership problems

Symptom Likely cause Fix
Permission denied writing to a bind mount container user is not the folder's mapped owner :U, --userns=keep-id, or podman unshare chown
Files in my project folder are owned by 100999 container user 1000 without keep-id use --userns=keep-id, then podman unshare chown -R 0:0 to repair
Cannot delete files created by a container host sees a mapped owner podman unshare rm -r PATH
Denied even though owner looks right SELinux label add :z or :Z
Database refuses to start: "data directory has wrong ownership" the volume's owner is not the database user :U or podman unshare chown to the user's UID

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. In a default rootless setup (UID 1000, range 100000:65536), which host user owns files created by container UID 999?

    Container UID N from 1 maps to 100000 + N - 1, so 999 maps to 100998.
  2. 2. What does the U volume option do?

    U runs a chown on the content so that the container user can use it.
  3. 3. You want files you create from a development container to stay owned by you. Which option?

    keep-id maps your UID to the same UID inside the container so created files are yours.
  4. 4. Which is the safest order to back up a database volume by copying files?

    Copying files that change underneath you can produce an inconsistent backup.
  5. 5. Why mount the source volume with :ro during a tar backup?

    Read-only protects the original even if the command is wrong.

Summary

  • Permission errors on rootless volumes come from user ID mapping: container UID N is host UID start + N - 1 (and container root is you).
  • Fix ownership with :U for a service's data, --userns=keep-id for your own project files, or podman unshare chown for exact control.
  • Use podman unshare to inspect or delete files that containers created with mapped owners.
  • Back up with podman volume export/import or a helper container running tar, preferably with the application stopped.
  • Always test a restore, and avoid chmod 777 shortcuts.

Next: Podman Networks and Netavark