VS Code Devcontainers with Podman on Ubuntu 25.10 + Authd

Project Discussion Desktop
, , , ,
1

Getting VS Code devcontainers to work with Podman on Ubuntu 25.10 may require extra configuration to work smoothly - using an authentication service such as authd likely requires some additional steps.

Disclaimer: I did not reproduced these steps on a new machine to verify correctness. Most of these steps are non-destructive, but obviously use your best judgement.

Issue #1: UID too large

By default, VS Code tries to remap your local UID into the container. This fails in Podman environments when the uid is unusually large (most commonly seen with a corporate identity provider). You need to tell VS Code to use the container’s default user instead.

The changes required for devcontainer.json:

JSON

{
  // The crucial Podman fixes:
  "updateRemoteUserUID": false,
  "containerUser": "ubuntu",
  
  // Other settings as normal. 
  ...
}

Issue #2: File permissions errors

At this point you might be able to launch the container but may have permission issues on files inside the container. This appeared to be due to the container filesystem not mapping ownership into the container. I was unable to find a way to fix this in a way that is compatible with Docker, besides this hack:

Create an wrapper executable to launch podman.

#!/bin/bash
ARGS=()

for arg in "$@"; do
    # 1. Drop any  --userns flags passed by VS Code.
    [[ "$arg" == --userns=* ]] && continue

    ARGS+=("$arg")

    # 2. Inject our mapping on run / create (ignore volume/network subcommands).
    if [[ "$arg" == "run" ]] || [[ "$arg" == "create" && " ${ARGS[*]} " != *" volume "* && " ${ARGS[*]} " != *" network "* ]]; then
        ARGS+=("--userns=keep-id:uid=1000,gid=1000")
    fi
done

exec podman "${ARGS[@]}"

and configure VS Code accordingly:

"dev.containers.dockerPath": "/home/your.user/bin/podman-devcontainer"

It allows using the same devcontainer configuration with different OCI runtimes. If compatibility with different runtimes is not a concern, one could just set the podman-specific argument "runArgs": [ "--userns=keep-id:uid=1000,gid=1000" ] instead.

Without this step, id-mapped mounts will not work correctly - depending on file permissions this might not be immediately noticable, however certain file operations will likely fail at some point.

Issue #3: Snap updates to VS Code break Podman

Because VS Code is a Snap, it lives in versioned directories (like .../snap/code/233 and .../snap/code/234). Podman stores absolute paths in its internal database (should it? I’m not convinced). When VS Code updates, the path changes which causes Podman consistency checks fail, and you get a database configuration mismatch error when launching a container.

The Fix: Move Podman’s storage out of the Snap’s versioned directory and into a stable location in your home folder.

  1. Remove all of podman’s persistent data - Warning: destructive!:

    $ rm -rf ~/snap/code/current/.local/share/containers

  2. Set a persistent path in ~/.config/containers/storage.conf:

    [storage]
driver = "overlay"
graphroot = "/home/your.user/.local/share/containers/storage"

  3. Verify the change:

    $ podman system info | grep graphRoot:

  4. Build a new container

    Container files should appear in the new graphroot location.

When VS Code updates to the next version, the Podman path will not change, and your environment should not break.

Issue #4: [authd] Stale login name in /etc/subuid and /etc/subgid

If you migrated from a temporary local user to an authd account, your /etc/subuid and /etc/subgid files might still be pointing to your old username. Podman needs these to be accurate.

The Fix: Replace the stale username with your current uid or username in both files.

  1. Find your current uid.

    Shell

    $ id -u

  2. Update both /etc/subuid and /etc/subgid (e.g., replacing oldname, increase map range):

    Before

    oldusername:100000:65536

    After

    123456789:200000:65536

My Environment

  • OS: Ubuntu 25.10
  • Podman: 5.4.2 (deb)
  • VS Code: Version 234 (Snap)
  • Auth: authd

edit: updates to make id mapped mounts work correctly
update: same issues observed on 26.04 / 5.7.0.

3 Likes