Rootless Podman: subuid, subgid and Namespaces
Rootless Podman runs containers as a normal user by mapping a range of subordinate UIDs and GIDs into a user namespace.
Rootless is Podman default and its main selling point in CI: no daemon, no root. Most rootless failures trace back to missing subuid/subgid ranges or running inside an already-unprivileged container.
What it does
Rootless Podman uses a user namespace to map your single host UID to a range of UIDs inside the container, drawn from /etc/subuid and /etc/subgid. This lets an unprivileged user run multi-user images without a root daemon.
Common usage
# ensure a subuid/subgid range exists for the CI user
grep "^$(whoami):" /etc/subuid /etc/subgid
sudo usermod --add-subuids 100000-165535 --add-subgids 100000-165535 ciuser
# re-read the ranges after editing
podman system migrate
podman unshare cat /proc/self/uid_mapOptions
| Item | What it does |
|---|---|
| /etc/subuid | Maps a host UID range for the user namespace |
| /etc/subgid | Maps a host GID range for the user namespace |
| podman system migrate | Re-reads subuid/subgid after changes |
| podman unshare | Run a command in the rootless user namespace |
| --userns=keep-id | Map the container user back to your host UID |
In CI
The CI user needs a subuid/subgid range (commonly 65536 IDs). Running rootless Podman inside an already-unprivileged container needs either privileges or the vfs storage driver, since overlay mounts may be blocked. Privileged ports below 1024 are not bindable; map to high ports.
Common errors in CI
"cannot set up namespace using newuidmap: ... write to uid_map failed: Operation not permitted" or "potentially insufficient UIDs or GIDs available in user namespace" means /etc/subuid and /etc/subgid lack a range; add one and run podman system migrate. "newuidmap: usage" or "command not found" means the uidmap package is missing. "kernel does not support overlay" inside a container is fixed with --storage-driver=vfs.