Skip to content

Wayland on Windows Run a Wayland Compositor Directly in Your Windows Machine

Wayland is a display protocol, a protocol (and accompanying C library) spoken by a graphical application with a display server in order to communicate about both input to the application (keyboard, mouse, …) and about output from the application — that is, the rendered window. Wayland was developed to replace the X11 server on the Linux system. After quite a few years of incubation, it’s becoming much more common. It’s a far simpler and more attractive protocol compared to X11, allowing much more flexibility in developing custom compositors and control in the display compositor on how the client applications are shown and with less decades-old baggage to keep around and take into account.

So, what’s the problem?

Qt provides both a Wayland platform allowing you to run Qt applications as Wayland clients in a Wayland compositor and a library to build a Wayland compositor, both using QML or not, in the Qt Wayland module. However, that and Wayland, in general, are only available on Linux, which may prove to be a problem for many. Many projects that target a Linux embedded platform but are developed on Windows because of some tooling that is only available there or for any other reason end up using a Linux virtual machine, which is a far less than optimal solution. It has several disadvantages: worse performance, an OS and environment that you are not used to, possibly bad or no hardware support for some devices, and a clunky user experience.

A Better Solution

There is a better solution. With the WSL subsystem on Windows, it is actually possible to run directly (albeit through an X server and so far unfortunately only OpenGL software) a Wayland compositor and clients. By running a Wayland compositor directly in your Windows machine, you avoid all the aforementioned problems. In this blog post, I’ll explain how to do it.

First, you need to setup WSL2, following the guide at

After that, you need to install an X server for Windows. I’ve successfully tried both VcxSrv and Xming. Launch it, but make sure to disable access control. If you’re using VcxSrv or Xming, there is an option in the XLaunch utility for that.

Now open the terminal of the Linux distribution you installed from the Start menu (I’m using Ubuntu 20.04, but any distribution should work) and run these commands:

sudo apt update && sudo apt upgrade sudo apt install weston

If you picked another distribution, you may need to adapt these commands, but it should not be difficult.

We are almost there. Now we need to tell the compositor the location of the X server. To do that, you need to open the PowerShell from the Start menu, run the ipconfig command, and locate IPv4 address in the section about the WSL adapter (usually the last one). In the Linux terminal, that’s the address we need to use to connect to the X server:

export DISPLAY=<address>:0

Wayland also needs the XDG_RUNTIME_DIR environment variable to know where to put the socket file:

mkdir /tmp/xdg

export XDG_RUNTIME_DIR=/tmp/xdg

We are going to add this export line also at the end of the .bashrc file so that it’s run automatically every time a terminal is opened.

Now if you run weston, you should see it open a window. To then run a Wayland client, open another Linux terminal and run a Wayland client. Weston provides a few, such as weston-terminal. But you can also install and run any Qt application by using the -platform wayland command line parameter or exporting the QT_QPA_PLATFORM=waylandenvironment variable beforehand, provided you’ve installed the QtWayland module. On Ubuntu, that is only a sudo apt install qtwayland5 away.

That’s it! As I’ve said, at this point in time it has the limitation that OpenGL is only provided by LLVMpipe, which runs on the CPU. Microsoft is working on improvements to the WSL layer to make this whole experience better, including adding GPU acceleration. However, that version is not released yet to the broad public. You can, in the meantime, subscribe to the Windows Insider program to try a preview. See For a QML application, unless you have some custom item that does heavy rendering, it’s not a real problem if you can accept maybe less than 60 fps.


About KDAB

If you like this article and want to read similar material, consider subscribing via our RSS feed.

Subscribe to KDAB TV for similar informative short video content.

KDAB provides market leading software consulting and development services and training in Qt, C++ and 3D/OpenGL. Contact us.

3 thoughts on “Wayland on Windows”

    1. Yes, but for that you need Windows 11, and you need to opt into the Windows Insider Program.

  1. The article is about running a GUI from WSL, OK.
    is it possible to run a Win10 or Win11 client accessing the Linux app from a different machine via wayland?
    just like you’d run an X11 client on Win10 and access a Linux app on another machine

Leave a Reply

Your email address will not be published. Required fields are marked *