Wayland is a set of rules that explain how a display server and other programs, called clients, communicate with each other. It also includes a set of tools written in the C programming language to follow these rules. A display server that uses the Wayland protocol is called a Wayland compositor because it also combines images on the screen, like a window manager does.

Wayland was created by a group of volunteers, with Kristian Høgsberg leading the project. It is a free and open-source project, meaning anyone can use and improve it. The goal was to replace an older system called the X Window System with a safer and simpler way to manage windows on Linux and other Unix-like operating systems. The project’s code is shared under the MIT License, a type of license that allows people to use and share the software freely. The Wayland project also creates a version of the Wayland compositor called Weston.

Overview

The Wayland Display Server project was launched by Kristian Høgsberg, a developer at Red Hat, in 2008.

Around 2010, Linux desktop graphics began changing from a system where many different ways to render graphics all connected to the X server (which was the main part of the system) to a system where the Linux kernel and its components, such as Direct Rendering Infrastructure (DRI) and Direct Rendering Manager (DRM), became central. In this new system, window systems like X and Wayland were moved to the side. This change created a simpler graphics system that offers more flexibility and better performance.

Høgsberg could have added an extension to X, as many recent projects have done, but he chose to move X away from the main path between clients and hardware. This decision is explained in the project’s FAQ.

The Wayland protocol is described in a .xml file that comes with the Wayland compiler. This compiler can convert the wayland.xml file into C libraries that applications and compositor implementations can use. The official reference implementation for a Wayland compositor is called Weston. The project is also developing versions of GTK and Qt that render to Wayland instead of to X. Most applications are expected to support Wayland through these libraries without needing changes to the applications themselves.

Early versions of Wayland did not include network transparency, but Høgsberg noted in 2010 that it was possible. An attempt to add network transparency was made as a Google Summer of Code project in 2011, but it was not successful. Adam Jackson proposed methods for remote access to Wayland applications, such as "pixel-scraping" (like VNC) or sending a "rendering command stream" over the network (as in RDP, SPICE, or X11). By early 2013, Høgsberg was testing network transparency using a proxy Wayland server that sent compressed images to the real compositor. In August 2017, GNOME introduced the first pixel-scraping VNC server implementation under Wayland. Modern Wayland compositors handle network transparency through an xdg-desktop-portal implementation that uses the RemoteDesktop portal.

Many Wayland compositors also include an xdg-desktop-portal implementation to manage common tasks, such as a native file picker for applications, sandboxes like Flatpak (xdg-desktop-portal-gtk is often used as a fallback file picker), screen recording, network transparency, screenshots, color picking, and other tasks that may require user interaction. It is important to note that xdg-desktop-portal is not specific to Flatpak or Wayland and can be used with other packaging systems and windowing systems.

Software architecture

The Wayland protocol uses a client–server model. In this model, clients are graphical applications that ask for images to appear on the screen, and the server (called the compositor) is the service that controls how these images are shown.

The Wayland protocol has two layers:
1. A low-level layer that handles communication between the client and the compositor. This layer sends messages between the two and is usually built using Unix domain sockets on Linux and similar systems.
2. A high-level layer that manages the information needed for basic window system features. This layer is built as an "asynchronous object-oriented protocol."

The low-level layer was written manually in the C programming language. The high-level layer is created automatically from an XML file that describes the protocol. When the XML file changes, the C code for the protocol is updated to include the new changes, making the protocol flexible and easy to use.

The Wayland protocol is split into two libraries:
– libwayland-client: A library used by client applications.
– libwayland-server: A library used by the compositor.

The Wayland protocol is called an "asynchronous object-oriented protocol." In object-oriented systems, the compositor provides services as a group of objects. Each object has a name, methods (called requests), and events. Each request and event has arguments with names and data types. The protocol is asynchronous because requests do not wait for replies, which improves performance.

Clients can make a request on an object if the object’s interface supports it. The client must provide the required data for the request. The compositor responds by sending events to the client, either as a reply to a request or due to internal changes (like input from a keyboard or mouse). Errors are also sent as events.

For a client to use an object, it must first tell the server the ID it will use to identify the object. Objects in the compositor are either:
– Global objects: Advertised by the compositor to all clients when they are created or destroyed.
– Non-global objects: Created by other existing objects as part of their functionality.

Interfaces, along with their requests and events, define the Wayland protocol. Each version of the protocol includes a set of interfaces that must be supported by any Wayland compositor. Compositors can also add their own interfaces to extend the protocol. Each interface has a version number to track changes. Compositors must also show which versions of interfaces are supported.

The current interfaces of the Wayland protocol are listed in the file protocol/wayland.xml in the Wayland source code. This file includes all interfaces, their requests, events, and other details. These interfaces are the minimum required for any Wayland compositor to work.

Some basic interfaces in the Wayland protocol include:
– wl_display: A core object that represents the Wayland protocol itself.
– wl_registry: A global registry where the compositor lists all available global objects.
– wl_compositor: An object that combines different surfaces into a single display.
– wl_surface: An object that represents a rectangular area on the screen.
– wl_buffer: An object that provides content to be displayed on a surface.
– wl_output: An object that represents the visible area of a screen.
– wl_pointer, wl_keyboard, wl_touch: Objects that represent input devices like mice, keyboards, and touchscreens.
– wl_seat: An object that represents a group of input/output devices in a multiseat setup.

A typical Wayland client session starts by connecting to the compositor using the wl_display object. From there, the client can request the wl_registry object to find and use other objects, such as wl_compositor, to create surfaces for displaying application content.

Compositors can add their own interfaces to extend the protocol. For example, the Weston compositor used these features to test new ideas, some of which later became part of the core protocol.

The XDG-Shell protocol is an extension used to manage surfaces under Wayland compositors. It replaces the older wl_shell methods, which are now outdated. The xdg-shell protocol provides two main interfaces:
– xdg_surface: A window that can be moved, resized, or maximized.
– xdg_popup: A popup or menu that appears temporarily and is linked to another surface.

The IVI-Shell is another extension for the Wayland protocol, designed for in-vehicle infotainment systems.

The Wayland protocol does not include a rendering API. Instead, it uses a direct rendering model, where the client is responsible for rendering the content of windows.

Comparison with other window systems

There are several differences between Wayland and X in terms of performance, how easy the code is to update, and security. XWayland is an X Server that runs as a client in the Wayland system. This allows X11 applications to be displayed in a Wayland environment. This is similar to how XQuartz works on macOS, letting X applications run in the native windowing system. XWayland was added to the X.Org Server version 1.16 to help move from the X Window System to Wayland. During this transition, XWayland allows users to run applications that have not yet been updated for Wayland. Toolkits like Qt 5 and GTK 3 can choose which display method to use when starting a program. Qt 5 lets users pick between X and Wayland by using a command when starting the program. GTK 3 allows users to select the preferred display method by changing a system setting called GDK_BACKEND.

Wayland compositors

Display servers that use the Wayland display server protocol are also called Wayland compositors because they also act as compositing window managers.

A library named wlroots is a flexible Wayland implementation that serves as a base for several compositors.

Some notable Wayland compositors include:

• Weston – an implementation created by the Wayland development team. For more information about Weston, see below.
• Enlightenment added Wayland support starting with version 0.20.
• KWin – the default Wayland compositor for KDE Plasma.
• Mutter – the default Wayland compositor for GNOME.
• Sway – a tiling Wayland compositor based on wlroots; it can be used as a direct replacement for the i3 X11 window manager.
• Hyprland – a tiling Wayland compositor written in C++. Features include dynamic tiling, tabbed windows, and a custom renderer that provides window animations, rounded corners, and Dual-Kawase Blur on transparent windows.
• Woodland – a window-stacking Wayland compositor for Wayland written in C, inspired by TinyWL and focused on simplicity and stability.
• niri – a scrollable-tiling Wayland compositor written in Rust.
• labwc – a window-stacking Wayland compositor for Wayland based on wlroots, inspired by Openbox. It uses a similar approach and coding style to Sway.
• Phoc – a Wayland compositor for mobile devices like the PinePhone, using the wlroots library. It is often used with the Phosh mobile shell.
• River – a Wayland compositor based on wlroots, written in Zig. It provides its own protocol for window management and does not manage windows directly.

Weston is a Wayland compositor that was previously developed as the main example of the Wayland protocol by the Wayland project. It is written in C and released under the MIT License.

Weston officially supports only Linux because it depends on features specific to the Linux kernel, such as kernel mode-setting (KMS), the Graphics Execution Manager (GEM), and udev. On Linux, it handles input through evdev and buffer management through Generic Buffer Management (GBM). A prototype version for FreeBSD was announced in 2013.

The compositor supports High-bandwidth Digital Content Protection (HDCP) and uses GEM to share buffers between applications and the compositor. It has a plug-in system with "shells" that add elements like docks and panels. Applications are responsible for rendering their own window decorations.

Weston supports rendering through OpenGL ES or the pixman library for software rendering. It avoids using the full OpenGL stack to prevent including GLX and other X Window System dependencies.

A remote desktop interface for Weston was proposed in 2013 by a developer from RealVNC.

Maynard is a graphical shell that was created as a plug-in for Weston, similar to how GNOME Shell is a plug-in for Mutter.

Raspberry Pi Holdings, in partnership with Collabora, released Maynard.

The code in Weston for handling input devices (keyboards, pointers, touch screens, etc.) was separated into its own library called libinput. This change was first included in Weston 1.5.

Libinput manages input devices for multiple Wayland compositors and also provides a general-purpose X.Org Server input driver. It aims to offer a single solution for multiple compositors, allowing them to handle input events consistently while reducing the need for custom input code. Libinput detects devices using udev, handles devices, processes input events, and abstracts input functionality.

Version 1.0 of libinput followed version 0.21 and added support for tablets, button sets, and touchpad gestures. This version ensures a stable application programming interface (API) and application binary interface (ABI).

As GNOME/GTK and KDE Frameworks 5 have updated their systems, Fedora 22 will replace X.Org's evdev and Synaptics drivers with libinput.

With version 1.16, the X.Org Server added support for libinput through a wrapper called xf86-input-libinput.

The Wayland Security Module is a proposal that resembles the Linux Security Module interface found in the Linux kernel.

Some applications, especially those related to accessibility, require special permissions that should work across different Wayland compositors. Currently, most applications under Wayland cannot perform tasks like taking screenshots or sending input events without using xdg-desktop-portal or gaining special access to the system. The security model used by Wayland also causes issues with mouse position tracking when typing in some games.

The Wayland Security Module is a method to assign security decisions within the compositor to a central security decision engine.

Adoption

The Wayland protocol is designed to be simple. This means that extra rules and tools must be created and used to build a complete system for managing windows. Many tools that create graphics already support Wayland. However, the people who make the user interfaces (called graphical shells) are working with the Wayland developers to create the needed extra tools.

Most major Linux systems use Wayland by default. Examples include:

• Debian uses Wayland as the default setting for GNOME since version 10 (Buster), released on 6 July 2019.
• Fedora started using Wayland as the default for GNOME in version 25 (22 November 2016). If the graphics driver cannot support Wayland, X.Org is used as a backup. Starting with version 34 (27 April 2021), Wayland is the default for KDE Plasma.
• Manjaro uses Wayland as the default in the GNOME edition of Manjaro 20.2 (Nibia), released on 22 November 2020.
• Raspberry Pi OS, a version of Debian, allows users to choose Wayland since version 11 (Bullseye), released on 3 December 2021. Wayland became the default in version 12 (Bookworm), released on 10 October 2023.
• Red Hat Enterprise Linux uses Wayland as the default setting in version 8, released on 7 May 2019.
• Ubuntu included Wayland by default in version 17.10 (Artful Aardvark). However, Ubuntu 18.04 LTS switched back to X.Org because of problems. Starting with Ubuntu 21.04 in 2021, Wayland is the default again.
• Slackware Linux added Wayland to its development version, -current, on 20 February 2020. This became version 15.0 in 2022, but Wayland is still not the default.

Software tools that support Wayland include:

• EFL supports Wayland completely, except for selection features.
• GTK 3.20 supports Wayland fully.
• Qt 5 supports Wayland completely and can be used to create both tools that manage windows and tools that use windows.
• SDL added support for Wayland in version 2.0.2 and made it the default in version 2.0.4.
• GLFW 3.2 supports Wayland.
• FreeGLUT has basic support for Wayland.
• FLTK supports Wayland since version 1.4.0 (November 2024).

Desktop environments that have been changed to work with Wayland instead of X include GNOME, KDE Plasma, and Enlightenment.

GNOME 3.20 was the first version to include a complete Wayland session. GNOME 3.22 improved Wayland support in GTK, Mutter, and GNOME Shell. GNOME 3.24 added support for Nvidia drivers that are not open-source under Wayland.

KDE Plasma began supporting Wayland in version 5. Version 5.4 included the first full Wayland session. Starting with KDE Plasma 6, Wayland is the default.

In November 2015, Enlightenment e20 was announced with full Wayland support.

Other software that supports Wayland includes:

• Intelligent Input Bus is working on adding Wayland support, which may be ready for Fedora 22.
• RealVNC released a preview of Wayland support in July 2014.
• wayvnc is a VNC server for Wayland systems based on wlroots.
• Maliit is an input method framework that runs under Wayland.
• kmscon supports Wayland with wlterm.
• Mesa includes Wayland support.
• Eclipse was made to run on Wayland during a student project in 2014.
• Vulkan WSI (Window System Interface) is a set of commands that work like EGL for OpenGL or GLX for X11. Vulkan WSI supports Wayland from the start and allows applications to use GPUs and display results on Wayland systems.
• Waydroid (formerly Anbox-Halium) is a tool that lets Android apps run on Linux systems using Wayland.

Mobile and embedded hardware that support Wayland includes:

• postmarketOS
• GENIVI Alliance (now COVESA): This group supports Wayland for in-vehicle infotainment systems.
• Jolla: Smartphones made by Jolla use Wayland. It is also used as the standard for Linux Sailfish OS on devices from other companies or Android devices modified by users.
• Tizen: Starting with version 2.x, Tizen supports Wayland for in-vehicle infotainment. From version 3.0 onward, Tizen uses Wayland by default.

History

Kristian Høgsberg, a Linux graphics and X.Org developer who previously worked on AIGLX and DRI2, began Wayland as a side project in 2008 while employed by Red Hat. His goal was to create a system where "every frame is perfect," meaning applications would have enough control over rendering to avoid tearing, lag, redrawing, or flickering. While driving through Wayland, Massachusetts, the idea became clear, leading to the project's name (Weston and Maynard are nearby towns in the same area).

In October 2010, Wayland became a project under freedesktop.org. At that time, the developer mailing list was moved to wayland-devel, which, as of 2026, is managed through GNU Mailman.

Initially, the Wayland client and server libraries were released under the MIT License, while the reference compositor Weston and some example clients used the GNU General Public License version 2. Later, all GPL code was changed to the MIT License to simplify sharing code between the reference implementation and libraries. In 2015, it was found that Wayland used an older version of the MIT License, so the license text was updated to match the current version used by the X.Org project (known as the MIT Expat License).

Wayland works with all Mesa-compatible drivers that support DRI2, as well as Android drivers through the Hybris project.