The files /etc/subuid and /etc/subgid give a user a private range of user and group IDs to use inside a container. Rootless containers map root and other users inside the container onto that range. Without an entry, which should cover at least 65,536 IDs, rootless commands tend to fail.
Why a range is needed
A container with several users inside it, such as root, a service account and a build user, needs several distinct IDs. An unprivileged host user owns only one ID. The subordinate ranges let the kernel map many container IDs onto a block of host IDs that belong to that user alone and map to no real account.
Docker's remap documentation gives a worked example. An entry such as testuser:231072:65536 means processes started by testuser that run in a user namespace are owned by host UID 231072, shown as root inside, up to host UID 296607. Host UID 231073 appears as UID 1, and so on.
Reading the format
Each line has three fields separated by colons:
| Field | Meaning | Example |
|---|---|---|
| User | Name or numeric ID of the owner | testuser |
| Start | First host ID, treated as 0 inside the namespace | 231072 |
| Count | How many IDs are available | 65536 |
You can check yours with:
grep "^$(whoami):" /etc/subuid /etc/subgid
Docker's rootless prerequisites ask for at least 65,536 subordinate IDs in each file, and for the newuidmap and newgidmap tools, which the uidmap package usually provides.
Security reasons the ranges must not overlap
Docker stresses that ranges must not overlap, so that one user's namespaced process cannot reach into another's. On most distributions system tools manage the ranges when users are added. On some, adding a group does not add it to these files and you must edit them by hand.
If a process escalates outside the namespace, it is running as a high, unmapped ID on the host. That is the security value of the whole scheme.
Common failures
- Missing entry. Rootless Podman's documentation says that if the files are not set up for a user, commands can easily fail.
- Identity providers. Podman notes that some identity providers, with FreeIPA named as an example, integrate subuid and subgid support, but many do not.
- Too few IDs. A standard rootless setup gives containers 65,536 IDs. An image that uses a higher UID or GID cannot be used, and builds that try may fail.
- More than five ranges. Docker says the kernel limits the mapping files to five entries, so Docker uses only the first five mappings for a user.
A quick troubleshooting order
- Confirm the user has lines in both files.
- Confirm the count is at least 65536.
- Confirm no other user's range overlaps.
- Confirm newuidmap and newgidmap are installed.
- Retry the install script or command and read its first error.
For the full setup, see rootless Docker prerequisites and setup. To choose between modes, see userns remap or rootless.
Safeguard can inventory the dependencies inside the images you run, and you can try a free scan at gold.safeguard.sh/scan.
Quick check
Is the subordinate ID range a real login account?
No. The IDs map to no real user on the host, so a process using them has no privileges there.
How many IDs does a rootless setup need?
Docker's prerequisites ask for at least 65,536 in both files for the user.
Sources
- Rootless mode, Docker Docs
- Isolate containers with a user namespace, Docker Docs
- Shortcomings of rootless Podman, Podman project
Last reviewed: 19 October 2026.
