Wayland: Difference between revisions

Latest revision as of 05:18, 5 July 2026

☶︎

This article or section needs to be expanded. Further information may be found in the related discussion page. Please consult the pedia article metapage for guidelines on contributing.

Wayland is a modern display server protocol intended as a replacement for the legacy X11 system.

For additional details, see NixOS Manual: Chapter - Wayland.

Checking for Wayland

To check if you are using Wayland, run the following command:

$ echo $XDG_SESSION_TYPE

If wayland is returned, you are running Wayland.

Setup

Two things are required for running Wayland: a compatible Display Manager, and a compatible Compositor.

☶︎

This article or section needs to be expanded. Further information may be found in the related discussion page. Please consult the pedia article metapage for guidelines on contributing.

Display Managers

Display Managers are responsible for handling user login.

The following Display Managers support using both X and Wayland protocols:

Graphical

gdm is the GNOME Display Manager.
sddm is the default Display Manager for KDE. Wayland support is currently experimental.

Text-based

Compositors

For the purposes of this basic overview, a compositor can be thought of as equivalent to an X Desktop Environment.

Note: It is important to remember that this is not actually the case as there are multiple differences between how X and Wayland work internally.

Wayland Native

Sway is an i3-like compositor.
Hyprland the dynamic tiling Wayland compositor that doesn't sacrifice on its looks.
Niri is a scrollable tiling compositor.

X and Wayland support

Mutter is the default compositor for the GNOME Desktop Environment.
KWin is the default compositor for the KDE Desktop Environment.

Applications

Not all apps support running natively on Wayland. To work around this, Xwayland should be enabled.

Note: Enabling XWayland varies slightly from Compositor to Compositor, and may already be enabled. Consult your Compositor's documentation and/or nix file for how to enable.

Electron and Chromium

Ozone Wayland (which uses Wayland native instead of Xwayland) support in Chromium and Electron based applications can be enabled by setting the environment variable "NIXOS_OZONE_WL" with NIXOS_OZONE_WL=1 (also see commit).

As of NixOS 25.05 ("Warbler"), if XDG_SESSION_TYPE is unset or set to "wayland", chromium and electron apps will default to wayland native. This ignores the DISPLAY environment variable.

Declaratively (permanent)

NixOS

❄︎ /etc/nixos/configuration.nix

environment.sessionVariables.NIXOS_OZONE_WL = "1";

Imperatively (each time an application is launched)

Example: to launch code (📦︎ vscode)

$ NIXOS_OZONE_WL=1 code

Virtualization

To have wayland work inside of QEMU, you may need to pass -vga qxl.

@@ Line 6: / Line 6: @@
 == Checking for Wayland ==
-To check if you are using Wayland, run the following command
+To check if you are using Wayland, run the following command:
 <syntaxhighlight lang=console>
 $ echo $XDG_SESSION_TYPE
 </syntaxhighlight>
-If {{ic|wayland}} is returned, you are running Wayland
+If {{ic|wayland}} is returned, you are running Wayland.
 == Setup ==
@@ Line 16: / Line 16: @@
 Two things are required for running Wayland: a compatible Display Manager, and a compatible Compositor.
 {{Expansion|Verify completeness of DM and Compositor lists}}
 == Display Managers ==
 Display Managers are responsible for handling user login.
-The following Display Managers support using both X and Wayland protocols
+The following Display Managers support using both X and Wayland protocols:
 ==== Graphical ====
 * [https://github.com/NixOS/nixpkgs/blob/592047fc9e4f7b74a4dc85d1b9f5243dfe4899e3/nixos/modules/services/x11/display-managers/gdm.nix gdm] is the [[GNOME]] Display Manager.
 * [https://github.com/NixOS/nixpkgs/blob/592047fc9e4f7b74a4dc85d1b9f5243dfe4899e3/nixos/modules/services/x11/display-managers/sddm.nix sddm] is the default Display Manager for [[KDE]]. Wayland support is currently experimental.
 ==== Text-based ====
 * [https://github.com/NixOS/nixpkgs/blob/592047fc9e4f7b74a4dc85d1b9f5243dfe4899e3/pkgs/applications/display-managers/ly/default.nix ly]
 * [https://github.com/NixOS/nixpkgs/blob/592047fc9e4f7b74a4dc85d1b9f5243dfe4899e3/pkgs/applications/display-managers/emptty/default.nix emptty]
@@ Line 31: / Line 36: @@
 == Compositors ==
-For the purposes of this basic overview, a compositor can be thought of as equivalent to an X Desktop Environment. {{Note|It is important to remember that this is not actually the case as there are [https://en.wikipedia.org/wiki/Wayland_(protocol)#Differences_between_Wayland_and_X multiple differences] between how X and Wayland work internally}}
+For the purposes of this basic overview, a compositor can be thought of as equivalent to an X Desktop Environment. {{Note|It is important to remember that this is not actually the case as there are [https://en.wikipedia.org/wiki/Wayland_(protocol)#Differences_between_Wayland_and_X multiple differences] between how X and Wayland work internally.}}
 === Wayland Native ===
-* [[Sway]] is a i3-like compositor.
+* [[Sway]] is an i3-like compositor.
 * [[Hyprland]] the dynamic tiling Wayland compositor that doesn't sacrifice on its looks.
-* [[Niri]] is a scrollable tiling compositor
+* [[Niri]] is a scrollable tiling compositor.
 === X and Wayland support ===
-* [https://github.com/NixOS/nixpkgs/blob/nixos-23.11/pkgs/desktops/gnome/core/mutter/default.nix Mutter] is the default compositor for [[GNOME]] Desktop Environment.
+* [https://github.com/NixOS/nixpkgs/blob/nixos-23.11/pkgs/desktops/gnome/core/mutter/default.nix Mutter] is the default compositor for the [[GNOME]] Desktop Environment.
-* [https://github.com/NixOS/nixpkgs/blob/nixos-23.11/pkgs/desktops/plasma-5/kwin/default.nix KWin] is the default compositor for [[KDE]] Desktop Environment.
+* [https://github.com/NixOS/nixpkgs/blob/nixos-23.11/pkgs/desktops/plasma-5/kwin/default.nix KWin] is the default compositor for the [[KDE]] Desktop Environment.
 == Applications ==
-Not all apps support running natively on Wayland. To work around this, Xwayland should be enabled. {{Note|Enabling XWayland varies slightly from Compositor to Compositor, and may already be enabled. Consult your Compositor's documentation and/or nix file for how to enable}}
+Not all apps support running natively on Wayland. To work around this, Xwayland should be enabled. {{Note|Enabling XWayland varies slightly from Compositor to Compositor, and may already be enabled. Consult your Compositor's documentation and/or nix file for how to enable.}}
 === Electron and Chromium ===
-Ozone Wayland (which uses Wayland native instead of Xwayland) support in [[Chromium]] and [[Electron]] based applications can be enabled by setting the environment variable "<code>NIXOS_OZONE_WL</code>" with <code>NIXOS_OZONE_WL=1</code> ''(also see [https://github.com/NixOS/nixpkgs/commit/b2eb5f62a7fd94ab58acafec9f64e54f97c508a6 commit])''
+Ozone Wayland (which uses Wayland native instead of Xwayland) support in [[Chromium]] and [[Electron]] based applications can be enabled by setting the environment variable "<code>NIXOS_OZONE_WL</code>" with <code>NIXOS_OZONE_WL=1</code> ''(also see [https://github.com/NixOS/nixpkgs/commit/b2eb5f62a7fd94ab58acafec9f64e54f97c508a6 commit])''.
 As of NixOS 25.05 ("Warbler"), if <code>XDG_SESSION_TYPE</code> is unset or set to "wayland", [https://issues.chromium.org/issues/40083534#comment599 chromium and electron apps will default to wayland native]. This ignores the <code>DISPLAY</code> environment variable.
@@ Line 54: / Line 62: @@
 ===== NixOS =====
 {{File|3=environment.sessionVariables.NIXOS_OZONE_WL = "1";|name=/etc/nixos/configuration.nix|lang=nix}}
 ==== Imperatively (each time an application is launched) ====
 Example: to launch <code>code</code> ''({{Nixpkg|pkgs/applications/editors/vscode/vscode.nix|vscode}})''
 <syntaxhighlight lang="console">
@@ Line 63: / Line 73: @@
 == Virtualization ==
 To have wayland work inside of [[QEMU]], you may need to pass <code>-vga qxl</code>.