Using full desktop shell in WSL2 using WSLg (Wayland)

WSL2GUIWSLg-Wayland-en.md

Full desktop shell in WSL2 using WSLg (Wayland)

Note

If you want a more complete experience and already tried the Xvnc tutorial, maybe you should try the WSLg (Xwayland) instead.

Warning

This is a work in progress tutorial. Things done here may break existing functionality, so be careful!

In this tutorial, we will install and use a full GNOME Desktop environment in WSL2, without any external software. The only requirement is a working WSLg installation. At the moment, the instructions are only for Ubuntu (20.04, 22.04 and 24.04) distros and GNOME, but you can request me to test other distros and desktop environments.

Current limitations

• No fullscreen support
• No complete desktop support (with Display Manager)
• No support to clipboard (copy & paste) from/to Windows

Ubuntu

GNOME

Installing the required packages

1. Open a Ubuntu (20.04, 22.04 or 24.04) terminal. First of all, we need to make sure everything is up to date.

   sudo apt update
   sudo apt upgrade
   

2. WSL doesn't install the app store by default, so we can install it manually (or you can skip this step if you don't need it).

   sudo snap install snap-store
   

3. Now we can install the required packages. This may take a long time, so be patient.

   For Ubuntu 20.04 and Ubuntu 22.04

   sudo apt install ubuntu-desktop acpi-support-
   

   For Ubuntu 24.04

   sudo apt install ubuntu-desktop
   

Important

Note the minus sign (-) after the package acpi-support. This is necessary because it will be installed by default and installing it will render your distro almost unusable (see microsoft/WSL#10059), so we will tell apt to not install it.

Configuring the environment

1. Now we have everything installed, we must configure some things before using the GNOME Shell. First, we need to deactivate the GDM service, because unfortunately it doesn't work with WSLg yet (at least I didn't figure it out how to make it work).

   sudo systemctl mask gdm.service
   

2. Now we need to fix the directory /tmp/.X11-unix/, because it's mounted as read-only by default. We will create a new systemd unit.

   sudo systemctl edit --full --force wslg-fix.service
   

3. Paste the code below in the editor.

   For Ubuntu 20.04 and Ubuntu 22.04

   [Service]
   Type=oneshot
   ExecStart=-/usr/bin/umount /tmp/.X11-unix
   ExecStart=/usr/bin/rm -rf /tmp/.X11-unix
   ExecStart=/usr/bin/mkdir /tmp/.X11-unix
   ExecStart=/usr/bin/chmod 1777 /tmp/.X11-unix
   ExecStart=/usr/bin/ln -s /mnt/wslg/.X11-unix/X0 /tmp/.X11-unix/X0
   
   [Install]
   WantedBy=multi-user.target
   

   For Ubuntu 24.04

   [Service]
   Type=oneshot
   ExecStart=-/usr/bin/umount /tmp/.X11-unix
   ExecStart=/usr/bin/rm -rf /tmp/.X11-unix
   ExecStart=/usr/bin/mkdir /tmp/.X11-unix
   ExecStart=/usr/bin/chmod 1777 /tmp/.X11-unix
   ExecStart=/usr/bin/ln -s /mnt/wslg/.X11-unix/X0 /tmp/.X11-unix/X0
   ExecStart=/usr/bin/chmod 0777 /mnt/wslg/runtime-dir
   ExecStart=/usr/bin/chmod 0666 /mnt/wslg/runtime-dir/wayland-0.lock
   
   [Install]
   WantedBy=multi-user.target
   

4. Save the file and close the editor. Now we have to enable this service.

   sudo systemctl enable wslg-fix.service
   

5. The last step is to configure the GNOME Shell to start in nested mode.

   For Ubuntu 20.04

   sudo mkdir /etc/systemd/user/gnome-shell-wayland.service.d/
   sudo nano /etc/systemd/user/gnome-shell-wayland.service.d/override.conf
   

   For Ubuntu 22.04 and Ubuntu 24.04

   sudo mkdir /etc/systemd/user/[email protected]/
   sudo nano /etc/systemd/user/[email protected]/override.conf
   

6. Paste the code below in the editor.

   [Service]
   ExecStart=
   ExecStart=/usr/bin/gnome-shell --nested
   

7. Save the file and close the editor. Then close the distro terminal window.

8. Finally we will shutdown WSL.

   wsl.exe --shutdown
   

   The configuration is complete.

Starting the GNOME Shell

1. Now open again your distro terminal, then paste the command below.

   DESKTOP_SESSION=ubuntu \
   GDMSESSION=ubuntu \
   GNOME_SHELL_SESSION_MODE=ubuntu \
   GTK_IM_MODULE=ibus \
   GTK_MODULES=gail:atk-bridge \
   IM_CONFIG_CHECK_ENV=1 \
   IM_CONFIG_PHASE=1 \
   QT_ACCESSIBILITY=1 \
   QT_IM_MODULE=ibus \
   XDG_CURRENT_DESKTOP=ubuntu:GNOME \
   XDG_DATA_DIRS=/usr/share/ubuntu:$XDG_DATA_DIRS \
   XDG_SESSION_TYPE=wayland \
   XMODIFIERS=@im=ibus \
   MUTTER_DEBUG_DUMMY_MODE_SPECS=1366x768 \
   gnome-session
   

2. A GNOME Shell window will appear.

   Ubuntu 20.04

   

   Ubuntu 22.04

   

   Ubuntu 24.04

   

can anyone help me?I couldn't get into the gnome,it shows me something went wrong:(
I had tried many times qwq

i would like to know if this will work with kali and any of its desktop flavors would prefer kde, xfce, or mate

I figured out that theres sound on flatpaks like firefox but not the snap version of apps like firefox. Waydroid also has no sound too. Thats a problem because waydroid would easily replace bluestacks or mumu on windows with wsl2. I cant figure out how to get sound working for these apps do you have a way to fix that?

I just wanted to comment that I found a way to hide the mouse cursor on Ubuntu, so there isn't a ghosting effect. It should be showing the Windows cursor in an Ubuntu theme since the desktop GUI is from Linux.

https://askubuntu.com/questions/681269/how-do-i-hide-a-mouse-pointer-in-gnome-3

Can you revisit this to try to get waydroid sound working since wsl 2 is now open source?

Hi guys. It's been a long time since my last tutorial update. I'm sorry for not updating it with the last changes and your requests. There days are being very busy to me. But I will bring some updates as soon as possible.

Regarding the recent Microsoft action in finally opening the WSL2 code, maybe we will have some improvements, but I don't know, I'm not a experienced C/C++/Linux programmer. But I wish they will improve the WSLg backend. My biggest dream is to have a backend change, throwing off the limited RDP seamless connection and bringing a graphics façade for WSL that render windows in 3D surfaces in Windows side. This would bring an enormous performance improvement, I think. It's a dream for now, but who knows the future.

@Timbo303 Did you try the Weston on Weston approach? Since WSLg uses Weston as a Wayland compositor you can run another Weston window where you can launch Waydroid. You won't need the full Ubuntu desktop and sounds works inside the Weston desktop shell.

I made a quick guide here https://gist.github.com/onomatopellan/c5220c0efddaff69aaff77cca80b7b8e

@Timbo303 Did you try the Weston on Weston approach? Since WSLg uses Weston as a Wayland compositor you can run another Weston window where you can launch Waydroid. You won't need the full Ubuntu desktop and sounds works inside the Weston desktop shell.

I made a quick guide here https://gist.github.com/onomatopellan/c5220c0efddaff69aaff77cca80b7b8e

I tried to follow your instructions. However weston doesn't start up for some reason giving me this error:

Date: 2025-06-01 CDT
[18:39:48.518] weston 14.0.1
https://wayland.freedesktop.org
Bug reports to: https://gitlab.freedesktop.org/wayland/weston/issues/
Build: 14.0.1
[18:39:48.518] Command line: weston
[18:39:48.518] OS: Linux, 6.6.87.1-microsoft-standard-WSL2+, #1 SMP PREEMPT_DYNAMIC Sun Jun 1 17:19:51 CDT 2025, x86_64
[18:39:48.518] Flight recorder: enabled
[18:39:48.518] Starting with no config file.
[18:39:48.519] Output repaint window is 7 ms maximum.
[18:39:48.519] Loading module '/usr/lib/x86_64-linux-gnu/libweston-14/wayland-backend.so'
[18:39:48.523] Error: Failed to connect to parent Wayland compositor: No such file or directory
display option: (none), WAYLAND_DISPLAY=wayland-0
[18:39:48.523] fatal: failed to create compositor backend

@Timbo303 Since this is somewhat off-topic let's continue in my gist.