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

   

Hi. What distro are you using? Can you provide some screenshot of your terminal with the command?

Somehow running with sudo solving the problems - and I don't know why - something with file privilagies. Sorry can't reproduce - I deleted the distro

When I run the final command to get the desktop I get this error
[1] 891 trace trap DESKTOP_SESSION=ubuntu GDMSESSION=ubuntu GNOME_SHELL_SESSION_MODE=ubuntu = =1
this is on a fresh install of 24.04 when I installed it on 22.04 it worked so I don't really know why it wont work on 24.04

Actually this works but where hw and sw dependant and flucky, but thanks for @tdcosta100

When I run the final command to get the desktop I get this error [1] 891 trace trap DESKTOP_SESSION=ubuntu GDMSESSION=ubuntu GNOME_SHELL_SESSION_MODE=ubuntu = =1 this is on a fresh install of 24.04 when I installed it on 22.04 it worked so I don't really know why it wont work on 24.04

Hi, @CarterPillow. Can you provide a screenshot showing your command and this error?

When I run the final command to get the desktop I get this error [1] 891 trace trap DESKTOP_SESSION=ubuntu GDMSESSION=ubuntu GNOME_SHELL_SESSION_MODE=ubuntu = =1 this is on a fresh install of 24.04 when I installed it on 22.04 it worked so I don't really know why it wont work on 24.04

Hi, @CarterPillow. Can you provide a screenshot showing your command and this error?

Well not long after I made that comment I uninstalled all my WSL instances to re make them all and so I just went to re do all the commands and now it works I don't have any idea what changed but the problem is gone now but ill return with more details if it comes back @tdcosta100

Nice! I'm glad it worked now, @CarterPillow. If something goes wrong, let me know.

It works, but I cannot get the screen to go full screen or change its dimensions. lmk if there is a config for that

It works, but I cannot get the screen to go full screen or change its dimensions. lmk if there is a config for that

Bro it's literally in the last command you enter.

MUTTER_DEBUG_DUMMY_MODE_SPECS=1366x768

Change the resolution to 1920x1080 for example

Just found that if you do gnome-session DISPLAY 0 you will get a full screen thing, but then when I add the other parts that make it work in the front, it will stop working

Thanks for this guide! Everything installed ok. I only observe some mouse cursor ghosting. Is this normal or there is a way to get rid of it? And second, is it possible to launch gnome without having to copy / paste a bunch of parameters during the launch command? Maybe there is a way to use some kind of batch file to launch?

DESKTOP_SESSION=ubuntu
GDMSESSION=ubuntu
GNOME_SHELL_SESSION_MODE=ubuntu
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

The "Oh no! Something has gone wrong" is now displayed when attempting to open gnome after I installed an app from CLI. The app works. But no longer gnome-session does....

You can use Xwayland instead of Wayland directly. I will make a new tutorial showing how to do it, it's similar to the Xvnc tutorial.

For now, I don't know how to get rid of the double cursor, and how to make it work fullscreen.

So this has been working great so far, and again, I thank you for the effort you put into this tutorial.

Since budgie seems to be making problems, what about pop os? I saw a video of someone rocking it in wsl: https://m.youtube.com/watch?v=SYooHm8bzJU

Any help, please? I have been trying for 7 hours to run this.

Same here. Can't seem to get past this "Something went wrong" screen. I did get the setup screen the first time and clicked through it.

Hi, @tamboril. Could you please tell me your distro and version, and show the output of the following command?

systemctl cat wslg-fix.service

Hi, @tamboril. Could you please tell me your distro and version, and show the output of the following command?

systemctl cat wslg-fix.service

cat /etc/os-release
PRETTY_NAME="Ubuntu 22.04.4 LTS"

$ sudo systemctl cat wslg-fix.service
[sudo] password for jharris: 
# /etc/systemd/system/wslg-fix.service
[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

Everything seems to be correct. Could you please attach the file created by the following command?

journalctl -b --no-pager > ~/journalctl.txt

It will be created in your home directory, available in Windows Explorer.

Everything seems to be correct. Could you please attach the file created by the following command?

journalctl -b --no-pager > ~/journalctl.txt

It will be created in your home directory, available in Windows Explorer.

GH isn't letting me attach a .txt file. I'll try emailing.

I did notice that /tmp/.X11-unix/X0 does not show as a symbolic link with ls -dl. I tried moving it out of the way so I could re-create it like them service script does, but fails with "read-only filesystem":

srwxrwxrwx 1 jharris jharris 0 Jul 28 14:16 /tmp/.X11-unix/X0
jharris@JHARRIS-DESKTOP:~$ sudo mv /tmp/.X11-unix/X0 /tmp/X0_save
mv: cannot remove '/tmp/.X11-unix/X0': Read-only file system```

I was thinking in you attaching it as a file, because as text it would be truncated. You can remove the big text from your post. But I still need the entire file to figure it out what's happening.

Yeah it's not letting me attach it.:

I noticed that /tmp/.X11-unix is a read-only tmpfs filesystem of its own:
mount|grep X11

none on /tmp/.X11-unix type tmpfs (ro,relatime)

Did you enable the wslg-fix.service in the step 4 of Configuring the environment?

Did you enable the wslg-fix.service in the step 4 of Configuring the environment?

I had not. But I went back and did that. Now the symbolic link is there, but I still get the same results, even after shutting down and restarting wsl. I've probably done bad things to my Ubuntu instance over time. I don't mind nuking it and starting afresh. I'll report after that.

Nice. Unfortunately it's too easy to mess things up, maybe redoing everything will make it work well.

So this has been working great so far, and again, I thank you for the effort you put into this tutorial.

Since budgie seems to be making problems, what about pop os? I saw a video of someone rocking it in wsl: https://m.youtube.com/watch?v=SYooHm8bzJU

Hi, @phil9309. Followed the instructions and managed to install Pop_OS over Ubuntu 22.04. After installing it, you need to follow the steps of this tutorial. Then the launch command is:

DESKTOP_SESSION=pop \
GDMSESSION=pop \
GNOME_SHELL_SESSION_MODE=pop \
GTK_IM_MODULE=ibus \
GTK_MODULES=gail:atk-bridge \
NOTIFY_SOCKET=/run/user/`id -u`/systemd/notify \
QT_ACCESSIBILITY=1 \
QT_IM_MODULE=ibus \
XDG_CURRENT_DESKTOP=pop:GNOME \
XDG_DATA_DIRS=/usr/share/pop:$XDG_DATA_DIRS \
XDG_SESSION_TYPE=wayland \
XMODIFIERS=@im=ibus \
MUTTER_DEBUG_DUMMY_MODE_SPECS=1366x768 \
gnome-session

You can see it's very similar to the GNOME one. I hope you will be able to reproduce it.

This is really impressive, all my previous attempts at launching gnome in wsl2 failed. Will try this later. Also, see my wsl2 sway repo for how I managed to sync clipboard between windows and Wayland. Clipboard-sync may also work, but it didn't for me

Have half screen when i try to start gnome 47 and Manjaro hehe What can be wrong...

Regards,
Mattias Vinberg

Since this tutorial doesn't cover the use of VcxSrv, I cannot help you with your problem.

Great tutorial! Do you plan to upgrade it for Ubuntu 24.10?

@wartalski, when an Ubuntu 24.10 image for WSL gets ready, yes!