Skip to content

X11 forwarding from Docker containers

X11 forwarding allows graphical user interface (GUI) applications running inside a Docker container to be displayed on the host machine's desktop environment.^[600-developer-docker-run-command.md]

This technique enables containers to utilize the host's display server by forwarding the X11 protocol communication, typically through the X11 socket.^[600-developer-docker-run-command.md]

Prerequisites

Host Configuration (Windows)

On Windows, an X Server (such as VcXsrv) must be installed and running to handle the forwarded graphics.^[600-developer-docker-run-command.md]

  1. Install VcXsrv (e.g., vcxsrv-64.1.20.14.0.installer.exe).^[600-developer-docker-run-command.md]
  2. Configure the server (often referred to as XLaunch) to allow connections.
  3. Ensure the WSL environment has the DISPLAY environment variable correctly set to point to the host's IP.^[600-developer-docker-run-command.md]
    • Example setting for .bash_login: export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0^[600-developer-docker-run-command.md]

Implementation

To enable X11 forwarding, the Docker container must be granted access to the host's X11 socket and environment variables.

Key Parameters

  • Volume Mount (-v): Mount the host's X11 socket directory (/tmp/.X11-unix) into the container at the same path.^[600-developer-docker-run-command.md]
  • Environment Variable (-e): Pass the DISPLAY variable from the host shell into the container so the application knows where to render the window.^[600-developer-docker-run-command.md]

Command Syntax

The general pattern for running a container with GUI support is:

docker run -it \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -e DISPLAY=$DISPLAY \
    <image-name>
  • [[Docker]]
  • [[WSL]]

Sources

^[600-developer-docker-run-command.md]