X11 General GUI Development - Graphical output in the host using WSL

X11-GUI-[name] Docker containers forward their GUI output to the Windows host. This text provides a short description, what is required and how it works.

📍Note:
Earlier versions of this guide included instructions to install a dedicated WSL distribution for X11 forwarding, this is unnecessary. The container works fine using Docker’s built-in WSL2 environment, as shown below

Requirements

To enable X11 forwarding to Windows, the following is required:

• Docker: Docker Desktop must run using the WSL 2 backend
  (Enable via: Settings → General → Use the WSL 2 based engine).
• Host: XLaunch must be running on the Windows host to receive and display X11 output.
• Host: Make sure Windows Firewall allows connections to port 6000 (default for X server).

How It Works

When Docker starts (with the WSL2 backend enabled), it automatically creates and manages an internal WSL environment called docker-desktop.

Your Linux Docker container runs inside this environment, and because WSL2 supports interop with Windows, graphical output from the container can be forwarded to XLaunch (an X11 server for Windows).

To make this work, you need to set the DISPLAY environment variable in docker compose to:

DISPLAY=host.docker.internal:0

This is a special DNS name that allows containers to reach the Windows host.This is critical because XLaunch runs on the Windows side and listens on display :0 (port 6000).

✅ Example: Docker Compose Snippet

services:
    x11-gui-basic-service:                        #  Our service
        build:
            context: .  
            dockerfile: Dockerfile_X11-Gui-Base
        image: eelhart/x11-gui-base:latest # This name can be used to extend or chain this image.
        networks:
            network_common_X11_gui:
              ipv4_address: ${FIXED_IP1}
        environment:
            - PORT=${PORT}
            - DISPLAY=host.docker.internal:0    # This relays Linux GUI output through WSL to XLaunch on the Windows host.

License
This file is part of: X11 GUI Development Template Stack Copyright (c) 2025-2026 Nico Jan Eelhart.This repository is MIT licensed and free to use. For optional commercial support, customization, training, or long-term maintenance, see COMMERCIAL.md.

─── ✦ ───