Maaz Zindani

Loading the index…

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

A graphical Linux program (SFML) cannot open a display in WSL

ErrorFailed to open X11 display

Short answer

A Linux GUI program in WSL needs WSL 2 with WSLg, a DISPLAY value of :0 and the X11 socket folder linked to /mnt/wslg. Check those three things in order: update and restart WSL, echo DISPLAY, then look at /tmp/.X11-unix. The first one that is wrong is the cause.

  • Applies to WSL 2, WSLg, Ubuntu 24.04 on Windows 11
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check the display variable and the X11 socket folder in one go. DISPLAY should be :0 and /tmp/.X11-unix should link to /mnt/wslg/.X11-unix.

    echo $DISPLAY
    ls -la /tmp/.X11-unix
  2. 2Match what you see, then jump to its fix

    1. 1Nothing exists under /mnt/wslg, or the distribution is set up for WSL 1WSL is out of date, or the distro runs on WSL 1Fix
    2. 2echo $DISPLAY prints nothing or another valueDISPLAY is empty or not :0Fix
    3. 3ls -la /tmp/.X11-unix does not show a link to /mnt/wslg/.X11-unix/tmp/.X11-unix is missing or no longer links to WSLgFix

What does the error look like?

  • Failed to open X11 display
  • cannot open display

Cause 1 of 3

WSL is out of date, or the distro runs on WSL 1

1Check

Linux GUI apps need WSL 2 and a WSL build that includes GUI support. Look for the WSLg folder inside the distro; it is created by WSLg.

ls /mnt/wslg

2Fix

Update WSL from an administrator PowerShell and restart it. A WSL 1 distribution must be converted to WSL 2.

wsl --update
wsl --shutdown

3Verify

Open the distro again and start a test X11 app (install x11-apps first).

sudo apt install x11-apps -y
xeyes

Confirmed by learn.microsoft.com

Did this fix it?

Cause 2 of 3

DISPLAY is empty or not :0

1Check

WSL normally sets DISPLAY at startup. A line in a shell profile can change it.

echo $DISPLAY
grep -n DISPLAY ~/.bashrc ~/.profile

2Fix

Remove the profile line that overrides it, or set the value for the session.

export DISPLAY=:0

3Verify

Run the program again.

xeyes

Confirmed by github.com

Did this fix it?

Cause 3 of 3

/tmp/.X11-unix is missing or no longer links to WSLg

1Check

WSLg expects /tmp/.X11-unix to be a symbolic link to /mnt/wslg/.X11-unix. Mounting /tmp from /etc/fstab can replace it.

ls -la /tmp/.X11-unix
grep -n "/tmp" /etc/fstab

2Fix

Recreate the link, and drop any /tmp entry from /etc/fstab.

sudo rm -r /tmp/.X11-unix
ln -s /mnt/wslg/.X11-unix /tmp/.X11-unix

3Verify

The X server socket X0 should be listed, and the program should open a window.

ls /tmp/.X11-unix

Confirmed by github.com

Did this fix it?

How do I stop it coming back?

  • Run wsl --update every few weeks, and restart WSL with wsl --shutdown afterwards.
  • Do not set DISPLAY in your shell profile in WSL 2 unless you use your own X server.
  • Keep the GPU driver current, as Microsoft asks for a vGPU driver.

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?

Related fixes

Servers

dnf cannot install MySQL on Amazon Linux 2023

dnf cannot find a mysql-server package on Amazon Linux 2023

Amazon Linux 2023 documents MariaDB, not MySQL, as its database server, with packages named mariadb105 and mariadb105-server.

3 causes, each with a fix

Next step

Want this handled for good?

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