This page covers running an Xpra server in a Linux distribution hosted by WSL and connecting to it from Windows. This is useful when applications should keep running after their client disconnects, or when the Linux session is to be used from another Xpra client.
It is not necessary to use Xpra just to show a Linux graphical application on Windows. On supported Windows 11 systems, WSLg can display Linux GUI applications directly in Windows. Xpra adds its usual persistent sessions, seamless windows, and remote-access features on top of that.
Use a current WSL 2 installation and a supported Linux distribution. From an elevated PowerShell prompt, a new installation can normally be created with:
wsl --installUse wsl --update to update an existing installation and
wsl -l -v to check that the distribution uses version 2.
Microsoft's WSL installation
guide has the current requirements and installation
alternatives.
WSLg is included with current WSL on Windows 11. It provides the Wayland and X11 display services used by Linux GUI applications, as well as audio and clipboard integration. The WSLg architecture overview explains how those pieces fit together.
Install the official Xpra packages in the WSL distribution. The default Debian and Ubuntu repositories provide outdated or broken downstream packages that do not work with current Xpra clients; see Distribution Packages. Run the automatic setup script inside the WSL distribution to configure the official repository and install Xpra:
curl https://xpra.org/get-xpra.sh | bash
For manual repository setup, see Download Xpra.
Install the native Windows Xpra client as well. The packaged
EXE or MSI installer is required for Windows
integration; see the client
documentation.
The Windows client can reach a WSL distribution directly, using
wsl:// connections: wsl.exe runs Xpra in the
distribution and the Xpra protocol is carried over its pipes. There is
no TCP port to bind, no password to choose and no SSH server to
install.
Remote host
and the WSL mode, pick a distribution (or leave the default
one), optionally enter a Linux user and a display number - leave it
empty to use the first free one from 100, enter the command
to run and click Start & Attach. Using the display
number of a session that is already running starts the command in that
session. Only seamless sessions are available for WSL at the
moment.Connect): choose the
WSL mode, then the same distribution, user and display
number to re-attach to a session that is already running. The display
number can be left empty when only one session is running. These
settings are kept when saving the session to a .xpra
file.The list of distributions is obtained from
wsl --list --quiet. Before connecting, the client verifies
that xpra can be found in the distribution and shows
installation instructions if it cannot.
# start xterm in a new session on display 100 of the "Ubuntu" distribution:
Xpra_cmd.exe start wsl://Ubuntu/100 --start=xterm
# or let Xpra choose a free display number, starting at 100:
Xpra_cmd.exe start wsl://Ubuntu/ --start=xterm
# start another application in the session that is already running:
Xpra_cmd.exe start wsl://Ubuntu/100 --start=xclock
# re-attach to it later:
Xpra_cmd.exe attach wsl://Ubuntu/100
# the display number can be omitted when only one session is running:
Xpra_cmd.exe attach wsl://Ubuntu/
# as a specific Linux user:
Xpra_cmd.exe attach wsl://alice@Ubuntu/
# using WSL's default distribution, and its only session:
Xpra_cmd.exe attach wsl://If a command cannot be started in a session that is already running,
a warning is shown and the client still connects to the session. When
attaching without a display number and more than one session is running,
the error lists them and one must be specified. Run
xpra list in the distribution to see the sessions and their
display numbers.
The distribution name is case-sensitive, names containing special
characters can be URL-encoded (ie: wsl://My%20Distro/100).
When the distribution or the user is omitted, WSL's configured default
is used. Passwords and ports are not accepted in wsl://
addresses.
Xpra_cmd.exe is preferable while testing because it
prints diagnostics; add -d wsl for details about the
wsl.exe process.
Closing or disconnecting the client terminates its
wsl.exe process, but the Xpra server keeps running in the
distribution, so applications are still there when re-attaching.
WSL stops a distribution shortly after its last wsl.exe
process has exited, whatever is still running in it, which would
terminate the sessions. To prevent this, the client leaves a hidden
wsl.exe process running after disconnecting: it keeps the
distribution running for as long as the Linux user has Xpra servers in
it, and exits once the last one has stopped. There is only one of these
per distribution and user, however many sessions and connections there
are. It can be turned off for a connection with
wsl://Ubuntu/100?keepalive=no, or for all connections by
setting the environment variable XPRA_WSL_KEEPALIVE=0, the
distribution then stops - and the sessions with it - about 25 seconds
after disconnecting.
The sessions do not survive wsl --shutdown or a Windows
restart. See the .wslconfig
documentation for WSL's own idle settings.
TCP connections are still useful for connecting other clients, ie: the HTML5 client. Bind Xpra only to WSL's loopback interface. This uses WSL's localhost forwarding and avoids exposing an unencrypted Xpra TCP listener to the network.
In WSL, start a session and an application (replace
xterm with an installed application if necessary):
XPRA_PASSWORD='choose-a-secret' xpra start :100 --bind-tcp=127.0.0.1:14500,auth=env --start=xterm
From PowerShell, set the same password for the client and attach to the session:
$env:XPRA_PASSWORD = 'choose-a-secret'
Xpra_cmd.exe attach tcp://127.0.0.1:14500Do not bind to 0.0.0.0 or a LAN address without
configuring suitable authentication and transport security. For access
from another computer, prefer an SSH connection or TLS and follow the authentication and security guidance.
systemd is only needed when Xpra or a related service should be
managed as a system service. Current WSL distributions may already
enable it. To enable it for a WSL 2 distribution, add the following to
/etc/wsl.conf:
[boot]
systemd=trueThen run wsl --shutdown from PowerShell and start the
distribution again. Microsoft's systemd in WSL
documentation has the version requirements and troubleshooting
details. Do not use the old third-party scripts that replaced WSL's init
process.
WSLg can provide GPU-accelerated OpenGL to applications running on
its display. This is distinct from client-side OpenGL rendering. Driver
availability and supported APIs depend on the Windows GPU driver, WSL
version, and hardware. To inspect the renderer in the distribution,
install its mesa-utils (or equivalent) package and run:
glxinfo -B
See server OpenGL acceleration for Xpra display choices and their limitations. In particular, a normal virtual Xpra display generally uses software rendering; using an existing WSLg display is a separate setup with different lifecycle and isolation trade-offs.
The following notes record the specific machine on which this was originally tested. They are not general WSL or Xpra installation instructions.
The machine was a Lenovo laptop with an NVIDIA GeForce RTX 3070
Laptop GPU. After a clean Windows 11 installation, Windows Update, the
NVIDIA WSL-capable driver, and Lenovo Vantage updates were installed.
WSL was then installed with an Ubuntu 20.04 distribution, followed by
mesa-utils and gedit; the latter appeared to
pull in additional Mesa packages needed by this particular test.
The resulting glxinfo -B reported direct rendering
through D3D12 and the NVIDIA GPU:
OpenGL vendor string: Microsoft Corporation
OpenGL renderer string: D3D12 (NVIDIA GeForce RTX 3070 Laptop GPU)
OpenGL core profile version string: 3.3 (Core Profile) Mesa 21.0.3
OpenGL version string: 3.1 Mesa 21.0.3
OpenGL ES profile version string: OpenGL ES 3.0 Mesa 21.0.3