Mapping UIDs for Rootless Podman DevContainers

Under rootless Podman, files a container writes to your workspace can land owned by a subordinate UID instead of you. This page fixes that with the keep-id user-namespace mapping, so container writes stay owned by your host user and Git keeps working.

Prerequisites

You need rootless Podman with subuid/subgid ranges configured.

  • Podman running rootless (podman info as your user).
  • /etc/subuid and /etc/subgid with a range for your user.
  • A devcontainer you can add runArgs to.

UID-mapping prerequisitesYou need subuid ranges, the keep-id arg, a build, and an ownership check.subuid rangefor your userkeep-idin runArgsBuildpodmanVerifyfile owner

Step-by-Step Implementation

  1. Confirm your subordinate ID range exists.
grep "^$USER:" /etc/subuid /etc/subgid
  1. Add the keep-id userns mapping so the container user maps to your host UID.
{
  "runArgs": ["--userns=keep-id"],
  "remoteUser": "vscode"
}
  1. Rebuild and let Podman apply the mapping.
devcontainer up --workspace-folder . --remove-existing-container
  1. Verify a container-created file is owned by you.
devcontainer exec --workspace-folder . -- touch /workspace/.owncheck && stat -c '%U' .owncheck

keep-id mappingkeep-id maps the container user directly to your host UID so files stay yours.Container uservscode / root insidekeep-id map-> your host UIDsubuid rangeother IDs map hereResultworkspace files owned by you

Common Pitfalls

Ownership problems under rootless are almost always a missing or wrong userns mapping.

UID triageA triage path from wrong ownership to a correct keep-id mapping.Files owned by a subuid, not you?YESAdd --userns=keep-idkeep-id set but still wrong?YESCheck subuid range covers the UIDOwnership is correct

SymptomRoot CauseRemediation
Files owned by a high subuidNo keep-id mappingAdd --userns=keep-id to runArgs
keep-id has no effectsubuid range too smallWiden the subuid/subgid range
Permission denied on mountContainer UID can't writeAlign remoteUser UID with keep-id
Works rootful, not rootlessAssumed root daemon behaviourUse keep-id under rootless

Conclusion

Rootless ownership comes down to one option: --userns=keep-id maps the container user to your host UID, so everything it writes to the workspace stays yours. Confirm your subuid range covers it, and bind-mount ownership stops being a rootless headache.

keep-id summarykeep-id keeps files host-owned given a subuid range and matching user.keep-id givesHost-owned filesWorking GitNo chown danceNeedsA subuid rangeMatching remoteUserPodman rootless

FAQ

What does --userns=keep-id actually do? It maps the container's user to your host user's UID/GID directly, instead of into a subordinate range. So a file the container writes to a bind-mounted workspace is owned by your host user, keeping Git and host tooling happy.

Why are my files owned by a huge UID like 100999? That is a subordinate UID from your /etc/subuid range — the default rootless mapping. Add --userns=keep-id so the container user maps to your real UID instead, and new files are owned by you.

Do I still need remoteUser with keep-id? Yes. remoteUser selects which container user runs, and keep-id maps that user to your host UID. Together they ensure the process runs as a non-root user that also owns workspace files correctly on the host.