Develop on Ubuntu 24.04 with Podman

Visual Studio Code with Podman on a Fresh Ubuntu 24.04 VM

This guide explains exactly how to set up Visual Studio Code (VS Code) with Podman on a clean installation of Ubuntu 24.04 LTS inside a virtual machine, and how to build and run the maui-docker project locally inside a Dev Container.

1. Prepare the System

After installing Ubuntu 24.04, open a terminal and install the required packages:

sudo apt update
sudo apt install -y podman podman-docker uidmap curl git x11-apps
snap install code --classic

Package overview

• Podman: Docker-compatible container engine
• podman-docker: enables Docker-CLI compatibility
• uidmap: required for rootless containers
• x11-apps: optional, useful to test X11 GUI forwarding
• code: Visual Studio Code - Our IDE

2. Enable the Podman User Socket

Enable the user socket so VS Code can communicate with Podman:

systemctl --user enable --now podman.socket

Add this line to your shell configuration (for example ~/.bashrc):

echo 'export DOCKER_HOST=unix:///run/user/$UID/podman/podman.sock' >> ~/.bashrc

Reload the configuration:

source ~/.bashrc

Create folder for your Source

mkdir ~/source

3. Configure Visual Studio Code

Start VS Code:

code .

Install these extensions:

• C#
• C# Dev Kit
• Dev Containers — ms-vscode-remote.remote-containers
• Container Tools

Optional: adjust your user settings (settings.json) so VS Code uses Podman directly:

{
    "dev.containers.dockerPath": "podman",
    "dev.containers.dockerSocketPath": "unix:///run/user/1000/podman/podman.sock",
    "containers.environment": {
        "DOCKER_HOST": "unix:///run/user/1000/podman/podman.sock",
        "CONTAINERS_STORAGE_CONF": "/home/dev/.config/containers/storage.conf",
        "XDG_DATA_HOME": "/home/dev/.local/share",
        "XDG_RUNTIME_DIR": "/run/user/${localEnv:UID}"
    },
    "containers.containerClient": "com.microsoft.visualstudio.containers.podman",
    "containers.orchestratorClient": "com.microsoft.visualstudio.orchestrators.podmancompose",
    "containers.commands.attach": "${containerCommand} exec -it ${containerId} ${shellCommand}",
    "dev.containers.defaultFeatures": {
        
    }
}

Install .NET SDK, there should be a message

4. Build the MAUI Docker Environment Locally

Clone the repository and build the container image on your own system:

cd ~/source
git clone https://github.com/MauiGtk/maui-docker.git
cd ~/source/maui-docker
podman build -t maui-env .

This creates a local image named maui-env that will be used by VS Code when opening the project inside a Dev Container.

5. Allow GUI Access (X11)

To run graphical MAUI GTK applications, allow the container to use your X display:

xhost +local:

(You can later restrict access again with xhost -local:.)

6. Clone the maui-linux project

You can just clone the maui-linux repository

git clone https://github.com/lytico/maui.git

or you could clone the lytico repository

git clone https://github.com/lytico/maui.git

I don't know witch is a better Point to start, in future maui-linux.net will provide it's own stable compilable repository

7. Open the Project in VS Code

Open the project folder:

cd ~/source/maui-docker
code .

Then run Ctrl + Shift + P → “Dev Containers: Reopen in Container”. VS Code will start a Podman container based on the included .devcontainer configuration.

8. Run the MAUI Sample Application

Inside the container terminal, execute:

cd /mauienv/maui/src/Controls/samples/Controls.Sample
dotnet run --framework net8.0-gtk

If everything is configured correctly, a GTK window should appear on your Ubuntu 24.04 desktop.

9. Troubleshooting

VS Code reports “Docker not found”

Ensure podman-docker is installed and DOCKER_HOST is set correctly.

GUI does not open / “cannot open display”

Verify $DISPLAY (e.g. :0) is set and that you have run xhost +local:.

Container fails to start

Check if the socket is active:

 systemctl --user status podman.socket

10. Summary

Component	Purpose
Ubuntu 24.04 VM	Clean test environment
Podman	Docker-compatible container engine
podman-docker	Docker CLI compatibility layer
podman.socket	API endpoint for VS Code
VS Code Dev Containers	Container-based development environment
X11 forwarding	Enables GUI applications inside containers

With these steps, a clean Ubuntu 24.04 VM can run **Visual Studio Code Dev Containers** using **Podman**, including full GUI support for **.NET MAUI GTK** applications.