Alpine Linux - User contributions [en]

Wayland

2026-02-07T08:54:31Z

Cubi: fixing it, previous one i edited in threw xdg missing errors for pipewire, THIS should be fine now as i just tested as it works in pipewire.

[https://en.wikipedia.org/wiki/Wayland%20(protocol) Wayland] is a new display protocol that aims to replace [[Xorg|X11]]. Wayland requires a [[Seat manager|seat manager]] to work.

The {{ic|setup-wayland-base}} script installs and enables [[elogind]] as [[Seat manager|seat manager]] besides enabling [[Repositories#Community|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]], [https://en.wikipedia.org/wiki/Mutter%20(software) Mutter] ([[GNOME]]'s compositor) and [https://en.wikipedia.org/wiki/KWin Kwin] ([[KDE]]'s compositor). The following [[:Category:Compositor|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 [https://biggo.com/news/202511040138_X11-Wayland-Security-Debate 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.

{{Pkg|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 {{ic|xwayland disable}}, say, near the top of the {{Path|~/.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:
{{Cmd|$ doas apk del xwayland}}

== Wayback ==
{{Main|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 <code>XDG_RUNTIME_DIR</code> variable to be set. When setting paths for {{ic|XDG_RUNTIME_DIR}}, at all times they should follow [https://specifications.freedesktop.org/basedir/latest/#variables '''XDG specifications'''].

{{Note|If <code>XDG_RUNTIME_DIR</code> variable is set inside startup script/file, it MUST be initialised before the Wayland compositor and the D-Bus session instances are started.}}

=== With elogind ===

When using [[elogind]] as a seat manager, it exports <code>XDG_RUNTIME_DIR</code> and other XDG environment variables automatically for each session. No further configuration is required. <code>XDG_RUNTIME_DIR</code> would be set as {{Path|/run/user/$(id -u)}} by '''elogind'''.

=== With pam_rundir ===

[https://github.com/jjk-jacky/pam_rundir pam_rundir] is a [[PAM]] module that provides the runtime directory variable. Installing the package {{pkg|pam-rundir}} takes care of dependencies and no further configuration is required. <code>XDG_RUNTIME_DIR</code> would be set as {{Path|/run/user/$(id -u)}} by pam_rundir.

=== With mkrundir ===

[https://git.sr.ht/~whynothugo/mkrundir mkrundir] is an executable that can be used to initialise the runtime directory explicitly by each user. To use <code>mkrundir</Code>, install the package {{pkg|mkrundir}} available in [[Repositories#Testing|testing]] repository. <code>XDG_RUNTIME_DIR</code> would be set as {{Path|/run/user-$UID}} by mkrundir. In your shell init script (e.g.: {{Path|~/.profile}} include an entry as follows at the '''top''' of the file {{Cat|~/.profile|...
export XDG_RUNTIME_DIR{{=}}$(mkrundir)
...}}

As per [https://git.sr.ht/~whynothugo/mkrundir mkrundir] website, this might have issues inside containers, due to privilege escalation.

=== Creating and exporting XDG_RUNTIME_DIR manually ===

Generally, care should be taken when configuring the <code>XDG_*</code> variables manually as this configuration may have errors or conflict with other utilities that do this automatically. Use this only on a system that's not using [[elogind]] and other solutions outlined above cannot handle this.

The <code>XDG_RUNTIME_DIR</code> can be initialised manually by adding below snippet to shell init scripts (e.g.: {{Path|~/.profile}}):

{{Cat|~/.profile|<nowiki>if test -z "${XDG_RUNTIME_DIR}"; then
export XDG_RUNTIME_DIR=/tmp/xdg/"${UID}"-xdg-runtime-dir
if ! test -d "${XDG_RUNTIME_DIR}"; then
mkdir -p "${XDG_RUNTIME_DIR}"
chmod 0700 "${XDG_RUNTIME_DIR}"
fi
fi
</nowiki>}}

== 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|XDG_RUNTIME_DIR]] to be set. Fix it using one of the above methods before proceeding.

== See also ==

* [[Kodi]]
* [https://wiki.archlinux.org/title/Wayland Wayland - Arch Wiki]
* [https://wiki.gentoo.org/wiki/Wayland Wayland - Gentoo Wiki]
* [https://en.wikipedia.org/wiki/Wayland_(protocol) Wayland (protocol) - Wikipedia]

[[Category:Desktop]]
[[Category:Wayland]]
[[Category:Compositor]]

Wayland

2026-02-07T06:40:02Z

Cubi: Current method that's listed on the page will throw a lack of permission error, this method actually works as I just tested on a fresh system just now.

[https://en.wikipedia.org/wiki/Wayland%20(protocol) Wayland] is a new display protocol that aims to replace [[Xorg|X11]]. Wayland requires a [[Seat manager|seat manager]] to work.

The {{ic|setup-wayland-base}} script installs and enables [[elogind]] as [[Seat manager|seat manager]] besides enabling [[Repositories#Community|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]], [https://en.wikipedia.org/wiki/Mutter%20(software) Mutter] ([[GNOME]]'s compositor) and [https://en.wikipedia.org/wiki/KWin Kwin] ([[KDE]]'s compositor). The following [[:Category:Compositor|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 [https://biggo.com/news/202511040138_X11-Wayland-Security-Debate 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.

{{Pkg|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 {{ic|xwayland disable}}, say, near the top of the {{Path|~/.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:
{{Cmd|$ doas apk del xwayland}}

== Wayback ==
{{Main|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 <code>XDG_RUNTIME_DIR</code> variable to be set. When setting paths for {{ic|XDG_RUNTIME_DIR}}, at all times they should follow [https://specifications.freedesktop.org/basedir/latest/#variables '''XDG specifications'''].

{{Note|If <code>XDG_RUNTIME_DIR</code> variable is set inside startup script/file, it MUST be initialised before the Wayland compositor and the D-Bus session instances are started.}}

=== With elogind ===

When using [[elogind]] as a seat manager, it exports <code>XDG_RUNTIME_DIR</code> and other XDG environment variables automatically for each session. No further configuration is required. <code>XDG_RUNTIME_DIR</code> would be set as {{Path|/run/user/$(id -u)}} by '''elogind'''.

=== With pam_rundir ===

[https://github.com/jjk-jacky/pam_rundir pam_rundir] is a [[PAM]] module that provides the runtime directory variable. Installing the package {{pkg|pam-rundir}} takes care of dependencies and no further configuration is required. <code>XDG_RUNTIME_DIR</code> would be set as {{Path|/run/user/$(id -u)}} by pam_rundir.

=== With mkrundir ===

[https://git.sr.ht/~whynothugo/mkrundir mkrundir] is an executable that can be used to initialise the runtime directory explicitly by each user. To use <code>mkrundir</Code>, install the package {{pkg|mkrundir}} available in [[Repositories#Testing|testing]] repository. <code>XDG_RUNTIME_DIR</code> would be set as {{Path|/run/user-$UID}} by mkrundir. In your shell init script (e.g.: {{Path|~/.profile}} include an entry as follows at the '''top''' of the file {{Cat|~/.profile|...
export XDG_RUNTIME_DIR{{=}}$(mkrundir)
...}}

As per [https://git.sr.ht/~whynothugo/mkrundir mkrundir] website, this might have issues inside containers, due to privilege escalation.

=== Creating and exporting XDG_RUNTIME_DIR manually ===

Generally, care should be taken when configuring the <code>XDG_*</code> variables manually as this configuration may have errors or conflict with other utilities that do this automatically. Use this only on a system that's not using [[elogind]] and other solutions outlined above cannot handle this.

The <code>XDG_RUNTIME_DIR</code> can be initialised manually by adding below snippet to shell init scripts (e.g.: {{Path|~/.profile}}):

{{Cat|~/.profile|<nowiki>if test -z "${XDG_RUNTIME_DIR}"; then
export XDG_RUNTIME_DIR=/tmp/${UID}-runtime-dir
if ! test -d "${XDG_RUNTIME_DIR}"; then
mkdir "${XDG_RUNTIME_DIR}"
chmod 0700 "${XDG_RUNTIME_DIR}"
fi
fi
</nowiki>}}

== 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|XDG_RUNTIME_DIR]] to be set. Fix it using one of the above methods before proceeding.

== See also ==

* [[Kodi]]
* [https://wiki.archlinux.org/title/Wayland Wayland - Arch Wiki]
* [https://wiki.gentoo.org/wiki/Wayland Wayland - Gentoo Wiki]
* [https://en.wikipedia.org/wiki/Wayland_(protocol) Wayland (protocol) - Wikipedia]

[[Category:Desktop]]
[[Category:Wayland]]
[[Category:Compositor]]