Wayland

Wayland is a new display protocol that aims to replace X11. Wayland requires a seat manager to work.

The setup-wayland-base script installs and enables elogind as seat manager besides enabling community repository and eudev.

Compositors

Display servers that implement the Wayland display server protocol are also called Wayland compositors because they additionally perform the task of a compositing window manager.

Multiple compositor implementations exist, including Sway, Mutter (GNOME's compositor) and Kwin (KDE's compositor). The following compositors are available in Alpine Linux.

XWayland

XWayland is an X server that can be instructed to run under Wayland so as to enable certain native X11 applications that have not been fully upgraded for Wayland. However, XWayland is a compatibility layer that is still not sufficiently effective to run native X11 graphical applications that still require running as root without advanced configuration, such as gparted, as XWayland does not have root permissions as per Wayland protocols and for the sake of enhanced security.

Although the X11 protocol design seeks to include flexibility and network transparency, consider that the use of XWayland reintroduces certain X11 design vulnerabilities into a Wayland session that was originally designed to avoid them, potentially including keylogging (capturing keystrokes)/taking screenshots/moving/resizing of other windows, although patches are applied where possible.

xwayland is typically bundled with compositors. To check performance without XWayland, attempt to disable it on the compositor first (this can be achieved, for example, in Sway, by adding the line xwayland disable, say, near the top of the ~/.config/sway/config file). If performance for your packages appears satisfactory, the package could be attempted to be removed in various compositors, including Sway, but it is a dependency on others, such as Labwc, river-classic, Cagebreak; ensure that apk does not indicate that it is a dependency to a given package when removing it:

$ doas apk del xwayland

Wayback

Wayback is another X11 compatibility layer, but unlike XWayland, it enables hosting a full X11 desktop environment on Wayland by enabling XWayland to run in rootful mode (future plans include enabling Wayback rootless mode). This enables Xfce and MATE to run fully under Wayland. However, as of December 2025, Wayback is still in alpha quality and thus not recommended for production.

XDG_RUNTIME_DIR

As per the protocol specifications, Wayland compositors require the XDG_RUNTIME_DIR variable to be set. When setting paths for XDG_RUNTIME_DIR, at all times they should follow XDG specifications.

Note: XDG_RUNTIME_DIR MUST be initialised before the Wayland compositor and the D-Bus session instances are started.

For techniques on properly initialising this variable, see XDG_RUNTIME_DIR.

Troubleshooting

error: XDG_RUNTIME_DIR is invalid or not set in the environment

The above error message appears when starting services/applications that require the environment variable XDG_RUNTIME_DIR to be set. Fix it using one of the above methods before proceeding.