Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

A GUI app in a Docker container on Linux says Gtk cannot open display :0

ErrorGtk: cannot open display: :0

Short answer

A container has no screen of its own. To draw on the host's X server it needs the host's DISPLAY value, the X11 socket directory from /tmp/.X11-unix mounted inside, and permission from the X server for the container's user. Missing any one of the three gives cannot open display. Add them to docker run, and allow access with xhost.

  • Applies to Docker Engine 28, X.Org X server, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Compare the display the host uses with what the container sees, and check that the socket for that display exists on the host.

    echo "host DISPLAY=$DISPLAY"
    ls -l /tmp/.X11-unix/
    docker run --rm IMAGE sh -c 'echo "container DISPLAY=$DISPLAY"; ls /tmp/.X11-unix'
  2. 2Match what you see, then jump to its fix

    1. 1container DISPLAY= prints an empty value, or :0 while the host prints :1DISPLAY is empty in the container, or names a different display than the hostFix
    2. 2ls /tmp/.X11-unix inside the container prints nothing or says no such file, while the host lists X0 or X1The X11 socket directory is not shared with the containerFix
    3. 3DISPLAY and the socket are both correct inside the container, and the program still cannot open the displayThe X server does not allow the container's user to connectFix

What does the error look like?

  • Gtk: cannot open display: :0
  • cannot open display: :0

Cause 1 of 3

DISPLAY is empty in the container, or names a different display than the host

1Check

A display name says where the X server is: an empty host part means a local connection on this machine, and the number picks the display. A container does not inherit the host's variable, and an image that hard-codes :0 fails when your session runs on another number.

echo "$DISPLAY"
docker run --rm IMAGE printenv DISPLAY

2Fix

Pass the host's own value into the container.

docker run --rm \
  -e DISPLAY="$DISPLAY" \
  IMAGE APP

3Verify

The container now prints the same value as the host.

docker run --rm -e DISPLAY="$DISPLAY" IMAGE printenv DISPLAY

Confirmed by xorg.freedesktop.org

Did this fix it?

Cause 2 of 3

The X11 socket directory is not shared with the container

1Check

On the host, the X server listens on a Unix domain socket named after the display number, /tmp/.X11-unix/X0 for display :0. A container has its own file system, so that socket is invisible unless the directory is bind-mounted.

ls -l /tmp/.X11-unix/
docker run --rm IMAGE ls -l /tmp/.X11-unix

2Fix

Bind-mount the directory at the same path, next to the DISPLAY variable.

docker run --rm \
  -e DISPLAY="$DISPLAY" \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  IMAGE APP

3Verify

The container lists the same socket as the host.

docker run --rm -v /tmp/.X11-unix:/tmp/.X11-unix IMAGE ls -l /tmp/.X11-unix

Confirmed by xorg.freedesktop.org

Did this fix it?

Cause 3 of 3

The X server does not allow the container's user to connect

1Check

The X server keeps a list of who may connect, and xhost shows whether access control is on and what is on the list. Processes in a container usually run as root, which is not the user of your desktop session.

xhost

2Fix

Add the container's user to the list. The server interpreted name si:localuser:USER names one local user. The broader form +local: allows every local connection, so keep it for a short test.

xhost +si:localuser:root
# a broad alternative for a quick test:
#   xhost +local:

3Verify

Start the container again. When you are done, remove the entry so access control is back to its normal state.

docker run --rm -e DISPLAY="$DISPLAY" -v /tmp/.X11-unix:/tmp/.X11-unix IMAGE APP
xhost -si:localuser:root

Confirmed by xorg.freedesktop.org

Did this fix it?

How do I stop it coming back?

  • Keep one working docker run line, or a Compose service with environment DISPLAY and the socket volume, in the project README.
  • Remove xhost entries when the session ends, and never use plain xhost + outside a throwaway test: it turns access control off for everyone.
  • Run the app as the same user as the desktop session where you can, so there is less to allow.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.