As someone who loves exploring new development workflows, I've become a huge fan of VS Code Dev Containers and their elegant approach of creating consistent, hassle-free development environments. The idea of having reproducible setups, easily shareable across teams without the usual "it works on my machine" headaches, has always appealed to me. Recently, however, I decided to move away from Docker Desktop and try Podman as my container engine of choice, particularly due to its open-source nature and compatibility with Docker commands. In this post, I'll share my journey, the challenges I faced, and the solutions I found while setting up Podman with VS Code Dev Containers.

Another key driver behind my switch to Podman was Docker's licensing model, which restricts free usage to small businesses with fewer than 250 employees and less than $10 million in annual revenue - a condition that my current company does not fulfill. On a personal note, I absolutely enjoy using my MacBook Pro for private projects and school, but at work, I'm working on Windows 11 with WSL2. This environment difference added an interesting layer to my transition to Podman, which I’ll focus on throughout this blog post.

https://docs.docker.com/subscription/desktop-license/

Of course, if switching from Docker to Podman was as straightforward as uninstalling one and installing the other, I probably wouldn't be writing this post right now. 😄 As I quickly found out, there are a few gotchas, configuration quirks, and compatibility hurdles - particularly when it comes to using Podman with VS Code Dev Containers on Windows 11. In this blog post, I'll walk through these pitfalls and the solutions I discovered, hoping it will save you some headaches if you decide to make a similar journey.

Let’s install this thing

Installing Podman on Windows 11 turned out to be pleasantly straightforward thanks to Winget, Microsoft's official package manager. Simply running the following commands in a terminal quickly installed Podman on my machine without any manual downloads or complicated setups.

winget install RedHat.Podman
winget install --id RedHat.Podman-Desktop # If you want some GUI like with Docker Desktop

Once installed, the initial configuration required running a couple of simple commands in my terminal to get things up and running. By executing the following two commands, Podman automatically created and launched a lightweight virtual machine to host the containers.

podman machine init
podman machine start

Configure Visual Studio Code

With Podman up and running, the next step is to configure Visual Studio Code to use Podman instead of Docker for Dev Containers. By default, VS Code assumes Docker as its container engine, so we'll need to explicitly instruct it to use the Podman executable.

Let’s add the following to our VS Code’s settings JSON.

{
    "dev.containers.dockerPath": "podman",
    "dev.containers.mountWaylandSocket": false,
}

When configuring VS Code to work with Podman, one setting turned out to be essential: "dev.containers.mountWaylandSocket": false. This configuration disables VS Code's default behavior of automatically mounting the Wayland socket - a communication channel used by GUI applications running on Linux to connect to the Wayland display server into the dev container. Wayland itself is a modern alternative to the traditional X11 display server used on Linux systems to handle graphical applications. The reason we have to disable this feature is that VS Code attempts to mount the Wayland socket via a UNC path (e.g., \\wsl.localhost\...), which Podman currently does not support, causing container startup failures. Disabling this mount prevents the issue, allowing containers to run correctly, though it means GUI apps using Wayland won't directly work from inside the container.

Leaving this enabled completely destroyed my Podman-based workflow with a wave of errors.

[159820 ms] Error: Command failed: podman run --sig-proxy=false -a STDOUT -a STDERR --mount type=bind,source=c:\Projects\work\dcozh\project,target=/workspaces/project,consistency=cached --mount type=volume,src=vscode,dst=/vscode --mount type=bind,src=\\wsl.localhost\Ubuntu-22.04\mnt\wslg\runtime-dir\wayland-0,dst=/tmp/vscode-wayland-ca8257f3-d0fb-4255-b61c-b7b054a6492a.sock -l devcontainer.local_folder=c:\Projects\work\dcozh\project -l devcontainer.config_file=c:\Projects\work\dcozh\project\.devcontainer\devcontainer.json -e ARM_CLIENT_ID=xxx -e ARM_CLIENT_SECRET=xxx -e ARM_TENANT_ID=xxx -e ARM_SUBSCRIPTION_ID=xxx --entrypoint /bin/sh vsc-project-5d4d105e3cdb6bc9fc29f9860c26ef10a6b5f2f1eb49a850144714fb334789ed-features -c echo Container started
[159820 ms] trap "exit 0" 15
[159821 ms] exec "$@"
[159821 ms] while sleep 1 & wait $!; do :; done -
[159821 ms]     at ytA (c:\Users\darth.vader\.vscode\extensions\ms-vscode-remote.remote-containers-0.397.0\dist\spec-node\devContainersSpecCLI.js:468:1260)
[159821 ms]     at bH (c:\Users\darth.vader\.vscode\extensions\ms-vscode-remote.remote-containers-0.397.0\dist\spec-node\devContainersSpecCLI.js:468:1002)
[159821 ms]     at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
[159821 ms]     at async TtA (c:\Users\darth.vader\.vscode\extensions\ms-vscode-remote.remote-containers-0.397.0\dist\spec-node\devContainersSpecCLI.js:485:3848)
[159822 ms]     at async iB (c:\Users\darth.vader\.vscode\extensions\ms-vscode-remote.remote-containers-0.397.0\dist\spec-node\devContainersSpecCLI.js:485:4963)
[159822 ms]     at async wrA (c:\Users\darth.vader\.vscode\extensions\ms-vscode-remote.remote-containers-0.397.0\dist\spec-node\devContainersSpecCLI.js:666:203)
[159822 ms]     at async DrA (c:\Users\darth.vader\.vscode\extensions\ms-vscode-remote.remote-containers-0.397.0\dist\spec-node\devContainersSpecCLI.js:665:14830)
[159822 ms]     at async c:\Users\darth.vader\.vscode\extensions\ms-vscode-remote.remote-containers-0.397.0\dist\spec-node\devContainersSpecCLI.js:485:1190
[159840 ms] Exit code 1
[159848 ms] Command failed:

Extending the container definition

Adjusting the VS Code settings alone won't fully solve our Podman compatibility issues. Even after updating VS Code's configuration, you'll likely run into permission errors when VS Code tries to initialize its server inside the dev container. To resolve these errors, we need to extend the container definition itself. Specifically, we need to add a few important properties to our devcontainer.json.

// For format details, see https://aka.ms/devcontainer.json. For config options, see the
// README at: https://github.com/devcontainers/templates/tree/main/src/ubuntu

{
    "name": "Ubuntu",
    // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
    "image": "mcr.microsoft.com/devcontainers/base:jammy",
    "features": {
        "ghcr.io/devcontainers/features/azure-cli:1": {},
        "ghcr.io/devcontainers/features/powershell:1": {},
        "ghcr.io/devcontainers/features/terraform:1": {}
    },

    // Environment Variables
    "containerEnv": {
        ... // Excluded for reasons of data security
    },

    // Use 'forwardPorts' to make a list of ports inside the container available locally.
    // "forwardPorts": [],

    // Use 'postCreateCommand' to run commands after the container is created.
    "postCreateCommand": "...", // Excluded for reasons of data security

    // Configure tool-specific properties.
    "customizations": {
        "vscode": {
            "settings": {
                ...
            },
            "extensions": [
                ...
            ]
        }
    },

    // Required configuration for Podman as container engine
    "remoteUser": "vscode",
    "containerUser": "vscode",
    "runArgs": [
        "--userns=keep-id"
    ]
}

By setting "remoteUser": "vscode" and "containerUser": "vscode", we explicitly instruct VS Code to run commands within the container as the non-root user vscode, avoiding permission issues with the root directory. Additionally, by adding "runArgs": ["--userns=keep-id"], we ensure Podman retains our host user's ID mappings inside the container, aligning file permissions seamlessly between the host and container environment. Without these changes, you might encounter persistent permission errors when VS Code attempts operations like creating directories or writing files inside the container.

Here the example of an error I ran into all the time without configuring the remoteUser and containerUser within my Dev Container definition.

[132904 ms] Start: Run in container: mkdir -p '/root/.vscode-server/bin' && ln -snf '/vscode/vscode-server/bin/linux-x64/e54c774e0add60467559eb0d1e229c6452cf8447' '/root/.vscode-server/bin/e54c774e0add60467559eb0d1e229c6452cf8447'
[132913 ms] 
[132913 ms] mkdir: cannot create directory '/root': Permission denied
[132913 ms] Exit code 1
[132923 ms] Command in container failed: mkdir -p '/root/.vscode-server/bin' && ln -snf '/vscode/vscode-server/bin/linux-x64/e54c774e0add60467559eb0d1e229c6452cf8447' '/root/.vscode-server/bin/e54c774e0add60467559eb0d1e229c6452cf8447'
[132923 ms] mkdir: cannot create directory '/root': Permission denied
[132923 ms] Exit code 1

Some last words

Switching from Docker to Podman for VS Code Dev Containers was more involved than I initially anticipated, but in the end the experience was rewarding. I learned a lot about the inner workings of containers, user namespaces and how VS Code integrates with different container runtimes. While Podman isn't yet a perfect drop-in replacement for Docker on Windows and WSL2 - especially when it comes to GUI or Wayland-related mounts. It comes remarkably close with some minor adjustments. Overall, I’m happy with the result, the knowledge gained during this journey, and especially the fact that I now have a fully functional, license-compliant setup for my day-to-day development at work. I hope this post helps you if you're considering a similar switch.

Finally, I'd like to emphasize that I'm sharing this experience as someone passionate about development containers, not as a container expert. I've documented this journey because I found it valuable, and I hope it's useful for others facing similar challenges. If you have any suggestions or improvements, feel free to reach out. I’d love to learn more!

Happy coding!