Setting Up a Graphical Desktop Environment in WSL2

Did you know that with Windows Subsystem for Linux (WSL), WSL2 specifically, you can use the entire Linux environment right on your Windows machine? I will walk you through the requirements and steps needed to set up a WSL2 graphical desktop environment.

Graphical Desktop Environment in WSL2

When can this be of use to software developers or engineers? There are several use-cases I can think of, but let’s just bring up general ones:

  • Doing away with Dual Boot. Boot on Windows 10/11 and still have full access to your Linux with Graphical Environment.
  • No resource (time and money) to build your own homelab using Proxmox or Unraid.
  • On Windows but needing to support a team mate’s issue on Ubuntu and no resource (storage & RAM) for dual boot or run Hypervisor, VirtualBox, VMWare, QEMU, etc. - USB Live mode is too slow.

Or simply, out of curiosity - can I run Graphical Applications in Windows 10/11 via WSL2?

You can. Let’s get started!

Requirements

Windows 10/11 with WSL2 Installed

wsl --install

Linux Distribution (e.g., Ubuntu)

Install a Linux distribution from the Microsoft Store, such as Ubuntu.

X Server for Windows

Install an X server to handle the graphical display from WSL. A popular choice is:

The X Server is a core component of the X Window System, managing graphical displays, handling inputs, and providing services to graphical applications. It is a client-server architecture that is extensible making it a powerful tool for creating and managing graphical environments on Unix-like operating systems. Run in Windows, it enables WSL2 Linux distributions to display desktop and applications with graphical interfaces on Windows.

Firewall Configuration

Configure the Windows firewall to allow connections to the X server and PulseAudio server if needed.

Necessary Packages in WSL

Install the required packages in your WSL environment. Open your WSL terminal and run:

sudo apt update

and cautiously perform an upgrade

sudo apt upgrade

Once your system is set with the packages you know you absolutely need and have frozen those you deem essential, install the necessary packages

sudo apt install xauth dbus-x11 gnome-shell

Setting Up the Environment

Install and Configure X Server

Install VcXsrv and configure it to start automatically when Windows starts. Make sure it listens on the default display port :0.

Install and Configure PulseAudio Server

Install a PulseAudio server on Windows. A recommended option is PulseAudio for Windows.

  • Download it from the official website.
  • Follow the installation instructions provided.

Understanding the Script

The full script is available to be copied over and executed in your environment. But before proceeding, it helps to understands what each of the calls is doing. This is necessary so that in case the script doesn’t work for you, you’ll know the code block to check or troubleshoot from.

Host & Services

Host IP for X Server & PulseAudio

export HOST_IP=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2; exit;}')

The Host IP forms the base for X Server and PulseAudio server address. We’re simply saving a copy now for efficient reuse later.

Default Login Mode

Changes the default login mode to a non-graphical target.

sudo systemctl set-default multi-user.target

The above command sets the Ubuntu in WSL2 to the following mode:

Non-Graphical Environment

The system starts in text-based multi-user mode without launching a graphical user interface (GUI). Users interact with the system through command line interfaces (CLI) or terminal sessions on the host machine or remote environment.

Service Initialization

Services required for a networked multi-user environment will be started. This typically includes network services, login services, and other essential background services that enable multiple users to log in and use the system.

Resource Usage

A non-graphical environment consumes fewer system resources (CPU, memory), which can be beneficial for systems with limited resources or occasional use of graphical environment only.

Suitability

This mode is suitable for servers, development environments, and systems where GUI is not necessary. It’s also useful for troubleshooting and recovery purposes when issues with the graphical environment arise.

Environment Variables for Ubuntu Desktop

XDG & GNOME Desktop Environment

Let’s setup “X Desktop Group” environment variables needed. XDG’s open standards and specifications ensure interoperability between various desktop environments and applications in Linux and Unix-like operating system.

This particular script sets things up for Ubuntu and GNOME.

export XDG_CURRENT_DESKTOP=ubuntu:GNOME 
export XDG_SESSION_DESKTOP=ubuntu 
export DESKTOP_SESSION=ubuntu 
export GNOME_SHELL_SESSION_MODE=ubuntu  
export XDG_CONFIG_DIRS=/etc/xdg/xdg-ubuntu:/etc/xdg 
export XDG_DATA_DIRS=/usr/share/ubuntu:/usr/local/share:/usr/share:/var/lib/snapd/desktop 
export XDG_MENU_PREFIX=gnome-  
export XDG_SESSION_TYPE=x11 
export XDG_SESSION_CLASS=user 
export GDK_BACKEND=x11

Graphics Library Configuration

Disables using Direct3D in the Mesa 3D graphics library.

export LIBGL_ALWAYS_SOFTWARE=1

There are still some issues with hardware accelerated rendering. For the time being, we’ll use software rendering until the issues are resolved or stable.

.Xauthority Generation

Password Placeholder

From hereon, {PASSWORD} should be interpreted as the literal password. You need to replace that string in the script with your own or modify several portions of the script using the placeholder.

There are several ways to do it but I leave that to you as an exercise. The modification you make for this part will also tell you your risk tolerance.

The Generator

A function to generate and set up the .Xauthority file, which is necessary for authenticating X sessions.

# Generate .Xauthority  
generate_xauthority() {
    local magiccookie=$(echo '{PASSWORD}' | tr -d '\n\r' | md5sum | awk '{print $1}')
    xauth add "$DISPLAY" . "$magiccookie"
    local userprofile="$(wslpath $(cmd.exe /c "<nul set /p=%UserProfile%" 2>/dev/null))"   
    if [ -f "$HOME/.Xauthority" ]; then     
	    cp "$HOME/.Xauthority" "$userprofile"
	    echo "copied $HOME/.Xauthority to $userprofile"
	    echo $magiccookie
    else
        echo "Unable to find $HOME/.Xauthority"
    fi 
}
generate_xauthority

When running a graphical desktop environment in WSL2, the .Xauthority file plays a crucial role in enabling secure communication between Linux GUI applications and an X server running on Windows. The setup script above generates and configures this file to ensure that the graphical applications can authenticate correctly with the X server.

The above script creates a new one and overwrites the previously copied .Xauthority to your Windows’ user profile directory. If you wish to run multiple GUI Linux on WSL2, you should modify the script to merge instead of overwrite.

Runtime Directory Permissions

Ensures that the runtime directory is properly set up and has the correct permissions.

# Extra check to synchronize runtime dir and ensure correct permissions export XDG_RUNTIME_DIR=/run/user/$(id -u) 
set_xdg_dir_permissions() {
	echo $XDG_RUNTIME_DIR
	if [ ! -d "$XDG_RUNTIME_DIR" ]; then
	     sudo mkdir $XDG_RUNTIME_DIR
		 echo "Created user runtime directories"
    fi
    sudo chmod 700 $XDG_RUNTIME_DIR && sudo chown $(id -un):$(id -gn) $XDG_RUNTIME_DIR 
}
set_xdg_dir_permissions  

DBUS Session Setup

Configures the DBUS session bus, which is necessary for many desktop applications to communicate with each other.

set_session_dbus() {
	local bus_file_path="$XDG_RUNTIME_DIR/bus"
	sudo chown -Rf $(id -un):$(id -gn) $XDG_RUNTIME_DIR
	export DBUS_SESSION_BUS_ADDRESS=unix:path=$bus_file_path
	if [ ! -e "$bus_file_path" ]; then
		/usr/bin/dbus-daemon --session --address=$DBUS_SESSION_BUS_ADDRESS --nofork --nopidfile --syslog-only &
	fi
}
set_session_dbus 

PulseAudio Configuration

Configures the PulseAudio server to enable sound.

echo "tcp:$HOST_IP"
export PULSE_SERVER="tcp:$HOST_IP"

Run the Custom Script

Copy the custom script provided below into a file, for example, setup_wsl_desktop.sh, and save it in your Ubuntu home directory.

# Host IP
export HOST_IP=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2; exit;}')  

# Initialize needed variables 
export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2; exit;}'):0.0
export LIBGL_ALWAYS_INDIRECT=0  

# Change default login mode
sudo systemctl set-default multi-user.target

# Setting up essential environment variables for Ubuntu desktop
# Ubuntu default desktop (GNOME Shell variant)
# https://wiki.gnome.org/Projects/GnomeShell
export XDG_CURRENT_DESKTOP=ubuntu:GNOME
export XDG_SESSION_DESKTOP=ubuntu
export DESKTOP_SESSION=ubuntu
export GNOME_SHELL_SESSION_MODE=ubuntu  

# Commonly referenced environment variables for X11 sessions 
# https://specifications.freedesktop.org/basedir-spec/latest/  
export XDG_CONFIG_DIRS=/etc/xdg/xdg-ubuntu:/etc/xdg
export XDG_DATA_DIRS=/usr/share/ubuntu:/usr/local/share:/usr/share:/var/lib/snapd/desktop
export XDG_MENU_PREFIX=gnome-  
export XDG_SESSION_TYPE=x11 
export XDG_SESSION_CLASS=user 
export GDK_BACKEND=x11  

# Disable using Direct3D in Mesa 3D graphics library 
export LIBGL_ALWAYS_SOFTWARE=1  

# Generate .Xauthority  
generate_xauthority() {
    local magiccookie=$(echo '{PASSWORD}' | tr -d '\n\r' | md5sum | awk '{print $1}')
    xauth add "$DISPLAY" . "$magiccookie"
    local userprofile="$(wslpath $(cmd.exe /c "<nul set /p=%UserProfile%" 2>/dev/null))"   
    if [ -f "$HOME/.Xauthority" ]; then     
	    cp "$HOME/.Xauthority" "$userprofile"
	    echo "copied $HOME/.Xauthority to $userprofile"
	    echo $magiccookie
    else
        echo "Unable to find $HOME/.Xauthority"
    fi 
}
generate_xauthority

# Extra check to synchronize runtime dir and ensure correct permissions export XDG_RUNTIME_DIR=/run/user/$(id -u) 
set_xdg_dir_permissions() {
	echo $XDG_RUNTIME_DIR
	if [ ! -d "$XDG_RUNTIME_DIR" ]; then
	     sudo mkdir $XDG_RUNTIME_DIR
		 echo "Created user runtime directories"
    fi
    sudo chmod 700 $XDG_RUNTIME_DIR && sudo chown $(id -un):$(id -gn) $XDG_RUNTIME_DIR 
}
set_xdg_dir_permissions  

set_session_dbus() {
	local bus_file_path="$XDG_RUNTIME_DIR/bus"
	sudo chown -Rf $(id -un):$(id -gn) $XDG_RUNTIME_DIR
	export DBUS_SESSION_BUS_ADDRESS=unix:path=$bus_file_path
	if [ ! -e "$bus_file_path" ]; then
		/usr/bin/dbus-daemon --session --address=$DBUS_SESSION_BUS_ADDRESS --nofork --nopidfile --syslog-only &
	fi
}
set_session_dbus 

# pulseaudio 
echo "tcp:$HOST_IP"
export PULSE_SERVER="tcp:$HOST_IP"`

Running X Server on Windows & GNOME Session

Execute the Script

In your Ubuntu WSL, make the script executable and run it.

chmod +x setup_wsl_desktop.sh ./setup_wsl_desktop.sh

If there are no errors, the environment is ready.

You may also add the script to your .bashrc to setup the environment everytime you login to your Terminal.

echo "./setup_wsl_desktop.sh" >> ~/.bashrc

Run GNOME Session

You can now start gnome-session to start sending data to the X Server in Windows.

gnome-session

or

gnome-session &

if you want to reuse the terminal and run gnome-session in the background.

In either case, you need to make sure the terminal that started gnome-session is not closed or terminated.

Windows X Server

If you configured X Server in Windows 10/11 as written here then all you have to do is bring to foreground the X Window :0 or whichever display you set it, as the profile may already be running in the background. If not; configure, save a profile, and run the profile.

PulseAudio Server

Understand that if you do not have this running as a service in Windows 10/11, you will not have audio in your Ubuntu Graphical Environment through Windows X Server.

If you do not have this as a service, run this before you start gnome-session.

Are you curious?

Will this run in Ubuntu through Docker, in Apple Silicon with XQuartz?


I hope that with the above breakdown of the provided script, I’ve accelerated your set up of a functioning graphical desktop environment in WSL2, which you can interact smoothly through the Windows host.