# Rootless Podman: subuid, subgid and Namespaces

> Rootless Podman runs containers as an unprivileged user via user namespaces. Reference for subuid/subgid, the namespace errors, and privileged-port limits in CI.

Source: https://latchkey.dev/learn/command-reference/podman-rootless  
Updated: 2026-06-30

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

```Terminal
# 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_map
```

## Options

| 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.

## FAQ

### Rootless Podman: subuid, subgid and Namespaces?

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.

### 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt