Docker Container GUI Display Using Wayland

Introduction

Wayland is a modern display server protocol for Linux that aims to replace the older X11 protocol. Wayland provides a more efficient and secure way to handle graphical display on Linux systems.

Starting from Ubuntu 26.04 LTS, Wayland has become the default display server protocol, and X11 support has been completely dropped. In this blog post, I would like to discuss how to run GUI applications from Docker container using Wayland on Ubuntu 26.04 LTS.

Examples

Starting with version 121, Firefox defaults to Wayland on Linux. If Wayland is not available, it will fall back to X11. We will use Firefox in a Ubuntu 26.04 Docker container as an example to demonstrate how to run GUI applications from Docker container using Wayland.

Firefox on Ubuntu 26.04

We could slightly modify the Dockerfile of Firefox on Ubuntu 24.04 for Ubuntu 26.04. The modified Dockerfile is as follows.

firefox.Dockerfile

FROM ubuntu:26.04

ENV DEBIAN_FRONTEND=noninteractive
ENV LC_ALL=en_US.UTF-8
ENV LANG=en_US.UTF-8

# Install Wayland-specific libraries and base tools
RUN apt-get update && apt-get install -y --no-install-recommends \
        ca-certificates \
        wget \
        gpg \
        dbus \
        libwayland-client0 \
        libwayland-egl1 \
        fonts-wqy-microhei && \
    apt-get clean

# Firefox Installation using Mozilla's APT repository
RUN install -d -m 0755 /etc/apt/keyrings && \
    wget -q https://packages.mozilla.org/apt/repo-signing-key.gpg -O- | tee /etc/apt/keyrings/packages.mozilla.org.asc > /dev/null && \
    gpg -n -q --import --import-options import-show /etc/apt/keyrings/packages.mozilla.org.asc | awk '/pub/{getline; gsub(/^ +| +$/,""); if($0 == "35BAA0B33E9EB396F59CA838C0BA5CE6DC6315A3") print "\nThe key fingerprint matches ("$0").\n"; else print "\nVerification failed: the fingerprint ("$0") does not match the expected one.\n"}' && \
    echo "deb [signed-by=/etc/apt/keyrings/packages.mozilla.org.asc] https://packages.mozilla.org/apt mozilla main" | tee -a /etc/apt/sources.list.d/mozilla.list > /dev/null && \
    echo 'Package: *\nPin: origin packages.mozilla.org\nPin-Priority: 1000' | tee /etc/apt/preferences.d/mozilla && \
    apt-get update && apt-get install -y --no-install-recommends \
        firefox && \
    apt-get clean

CMD ["firefox"]

To build the Docker image, please run the following command.

$ docker build -f firefox.Dockerfile -t firefox:26.04 .

Using Wayland

To start Firefox from the Docker container using Wayland, please run the following command. The operating system that hosts the Docker container must use Wayland as the display server protocol. In this case, I was running on Ubuntu 26.04 LTS which completely dropped support for X11 and only supports Wayland.

$ docker run -it --rm \
    -e XDG_RUNTIME_DIR=$XDG_RUNTIME_DIR \
    -e WAYLAND_DISPLAY=$WAYLAND_DISPLAY \
    -v $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY:$XDG_RUNTIME_DIR/$WAYLAND_DISPLAY \
    firefox:26.04

To verify that Firefox is running using Wayland, we could open the about:support page in Firefox and check the “Window Protocol” information. It should show “Wayland” instead of “X11”.

Using xWayland

To start Firefox from the Docker container using xWayland, i.e., the X11 compatibility layer for Wayland, please run the following command. The operating system that hosts the Docker container does not have to use Wayland as the display server protocol. In this case, Ubuntu 24.04 LTS or Ubuntu 26.04 LTS both worked.

$ xhost +
$ docker run -it --rm \
    -e DISPLAY=$DISPLAY \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    firefox:26.04
$ xhost -

To verify that Firefox is running using xWayland, we could open the about:support page in Firefox and check the “Window Protocol” information. It should show “X11” instead of “Wayland”, even if the host operating system is using Wayland as the display server protocol.

Conclusions

Wayland is the future of display server protocol for Linux. We should start using Wayland for GUI display as much as possible from now on.

References

• Docker Container GUI Display
• Firefox Installation In Ubuntu 24.04 Docker Images