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

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

2. Install Visual Studio Code

wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/microsoft.gpg > /dev/null
echo "deb [arch=amd64] https://packages.microsoft.com/repos/code stable main" | sudo tee /etc/apt/sources.list.d/vscode.list
sudo apt update
sudo apt install -y code

3. 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):

export DOCKER_HOST=unix:///run/user/$UID/podman/podman.sock

Reload the configuration:

source ~/.bashrc

4. Configure Visual Studio Code

Start VS Code:

code .

Install these extensions:

• Dev Containers — ms-vscode-remote.remote-containers
• Docker or Podman (Red Hat)

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

{
  "dev.containers.dockerPath": "/usr/bin/podman",
  "dev.containers.composeCommand": "podman-compose"
}

5. Build the MAUI Docker Environment Locally

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

git clone https://github.com/MauiGtk/maui-docker.git
cd 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.

6. 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:.)

7. Open the Project in VS Code

Open the project folder:

cd 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.