Under rootless Podman, container UID 1000 is host UID 100999 and your files look root-owned. The exact two-layer mapping, what keep-id changes and when it is the wrong fix.
The symptom
You run a container as an ordinary user with Podman, bind-mount a project directory, and let a build or an agent tool inside the container write some files. Back on the host, the new files belong to a user with an id like 100999, which you cannot edit without sudo. Or the reverse: files you own on the host appear inside the container as owned by root, and a process that runs as an unprivileged user in the image cannot write to them.
Both symptoms come from the same mechanism, rootless user namespaces, and both have the same family of fixes, of which --userns=keep-id is the best known. This guide explains the arithmetic exactly, so that you can predict the owner of any file instead of guessing, and shows where keep-id helps and where it does not. The rules here come from the podman-run documentation for --userns and from the mapping code visible in Podman v6.2.0's source. The companion calculator implements them; it does not run Podman, and nothing here was measured on a Linux host.
Coding-agent tools are a common way to meet this today, because they run tools in a container sandbox over your working tree. Gemini CLI v0.68.0, released on 10 November 2026, includes a fix that supplies --userns=keep-id for rootless Podman sandboxes, which is one example of the problem surfacing in practice. The fix is a single flag; the reasoning behind it is the subject of this guide.
Two layers of mapping
A rootless container has two user namespaces between it and the host.
The first is your own. When Podman starts rootless, it creates a user namespace in which id 0 is your real host UID, and ids 1 upwards are your subordinate ids from /etc/subuid. A typical entry is jenya:100000:65536: 65,536 ids starting at 100000 belong to user jenya for this purpose. So in this intermediate namespace, 0 maps to host 1000 (your UID, say), 1 maps to host 100000, 2 to 100001, and 65536 to 165535.
The second is the container's. By default, with --userns unset and nothing in containers.conf, Podman uses the intermediate namespace directly: container id N is intermediate id N. The documentation's table puts it as "host: $UID maps to 0", the default user account mapped to root in the container.
Put the two together and the default mapping is:
- container root (0) is you on the host, UID 1000;
- container UID N, for N from 1 to 65536, is host UID 100000 + N − 1.
So a process in the container running as UID 1000, a common default user in images, creates files owned on the host by 100000 + 1000 − 1 = 100999. That is where the strange number comes from. And a file you own on the host, UID 1000, appears inside the container as owned by 0, root.
What keep-id changes
The documentation describes keep-id as creating a user namespace where the current user's UID and GID are mapped to the same values in the container, and running the container's init process as that UID, overriding the image's USER unless you pass --user. The code that builds the mapping for the rootless case produces three segments. With UID 1000 and the subuid range above, they are:
- container 0 to 999 map to intermediate 1 to 1000, which are host 100000 to 100999;
- container 1000 maps to intermediate 0, which is you, host 1000;
- container 1001 to 65536 map to intermediate 1001 to 65536, host 101000 to 165535.
mode container uid host uid
default 0 1000 (you)
default 1000 100999
keep-id 0 100000
keep-id 999 100999
keep-id 1000 1000 (you)
keep-id 1001 101000With keep-id, a file you own on the host appears in the container as owned by 1000, and the container's main process runs as 1000, so it can write your files and the files it creates belong to you on the host. This is usually what a development or sandbox container wants.
The uid and gid options change which container id you are mapped to: --userns=keep-id:uid=200,gid=210 makes you 200 inside. The size option limits how many ids the namespace uses, which matters because the documentation warns that keep-id without a size uses all your subordinate ids, and --userns=auto stops working for new containers while such containers exist.
Worked example
Geetha maintains the fictional Belgavi's Book Store catalogue site. She mounts the repository into a Node.js image whose USER is node, UID 1000, and runs the build. Her host UID is also 1000, and her /etc/subuid line is geetha:165536:65536.
Default mode: the build runs as container 1000, which is host 165536 + 999 = 166535. It cannot write to the mounted repository, which is owned by host 1000, seen in the container as root. Either the build fails with permission denied, or someone adds --user root to make it work, after which every build artefact on the host is owned by Geetha, because container root is her. That second outcome looks fine on the host but means the build runs as root inside the container.
With --userns=keep-id: the build runs as container 1000, which is host 1000. It can write the repository and its output belongs to her on the host. Container root is now host 165536, a subordinate id, so a process that escalates to root inside gets no ownership of her files.
When keep-id is the wrong fix
keep-id assumes one host user and one interesting container user. It is not right when:
- the image expects to run as root, for example to bind a low port or install packages at start-up, because the main process now runs as your UID;
- the image runs services as several different users, for example a database as 999 and an application as 1000, because only one of them maps to you;
- the container is a long-lived service shared by several people, where your personal UID should not own its data.
Alternatives exist for those cases. The :U volume option tells Podman to change the ownership of the mounted source to match the container's user, which rewrites ownership on the host and so is only safe for directories that belong to the container. --uidmap and --gidmap let you build an explicit mapping. And podman unshare chown changes ownership from inside your intermediate namespace, so you can fix files owned by 100999 without sudo.
Inspecting the real mapping
Do not trust arithmetic alone on a real machine; read the mapping. podman unshare cat /proc/self/uid_map shows the intermediate namespace, and running cat /proc/self/uid_map inside a container shows the container's. Each line is container start, parent start and size. If the numbers differ from what you expected, /etc/subuid has a different range, or containers.conf sets a default userns, or the PODMAN_USERNS environment variable is set; the documentation lists that precedence.
Failure modes
- Build artefacts owned by 100999 on the host, from a container user without
keep-id. - A "fix" of
--user rootthat runs the whole build as root in the container. keep-idon an image whose entrypoint needs root, which then fails at start.:Uon a shared host directory, which rewrites its ownership for everyone.- GIDs forgotten: the same arithmetic applies to
/etc/subgid, and group-writable directories break the same way. - A user with no subordinate range at all, where only your own UID is mapped and every other container id appears as the overflow id, 65534.
What to automate
If a tool starts containers on a user's behalf, as agent sandboxes do, make the user-namespace mode an explicit, logged setting rather than an accident of defaults, and check after start-up that the container's main UID can write the mounted workspace. A one-line probe, writing and removing a file in the workspace, catches a wrong mapping before the agent's first real step.
Verify it
Run the companion calculator with your own /etc/subuid line and UID, and compare its output with /proc/self/uid_map inside a test container. Its nine tests cover the default and keep-id segments, the 100999 case, a custom uid, and unmapped ids.
Run the example yourself
The UID mapping calculator for the default and keep-id modes, with an /etc/subuid parser, an inverse mapping and nine tests. It does not run Podman. Companion code on GitHub; its README lists the prerequisites, exact commands, expected output and limits.