Skip to content

Wayland support

Jump to bottom Edit New page
Daniel Kondor edited this page Oct 1, 2025 · 8 revisions

Wayland support

The latest version of Cairo-Dock (3.6.0) includes support for running on Wayland, under compositors that support the layer shell protocol. It has been tested with recent versions of Wayfire, labwc, KWin / KDE Plasma, Cosmic, sway and Hyprland. Note that GNOME Shell / Mutter, including the default Ubuntu desktop, is unfortunately not supported.

Requirements

Compilation: see the guide. Note that all optional dependencies are required. When configuring, the CMake summary should include the following:

--  * With EGL support    : yes (1.5)
--  * With Wayland support: yes (1.22.0)
--  * With Wayland taskbar: yes
--  * With Wayfire IPC    : yes
--  * With gtk-layer-shell: yes

To be usable, the following protocols need to be supported by the compositor:

Optionally, if using Wayfire, this plugin provides the "present windows" feature (when an icon with a group of windows is clicked).

Using Cairo-Dock in a Wayland session

For now, it is recommended to first set up your session as normal (using any session files provided with your compositor) and then configure your compositor to autostart Cairo-Dock upon log in. This typically requires a compositor-specific setting (e.g. if using Wayfire, you can use WCM, or if using KWin / KDE Plasma, you can add autostart programs in your system settings).

Alternatively, if you session is based on systemd, you can use the unit provided by Cairo-Dock to make it start automatically -- see here.

An unofficial "desktop session" based on Wayfire is also provided here: https://github.com/dkondor/cairo-dock-wayland-session

Main features working

  • Dock positioning along a screen edge and keeping above / below and reserving space with the layer-shell protocol.
  • Proper positioning of subdocks, menus and dialogs.
  • Hardware acceleration with EGL.
  • Taskbar.
  • Hiding and recalling docks hidden or kept below.
  • HiDPI displays only with integer scale factors.
  • Wayfire-specific features: custom protocol for recalling the dock, scale for "present windows", toggle menu feature.
  • KWin-specific features: workspaces, detecting if windows overlap the dock, tracking window positions among workspaces
  • Labwc / Cosmic: basic support for workspaces (display and switching; only one "workspace group" supported, this can lead to problems with multiple monitors)
  • Cosmic: detecting if windows overlap the dock

Known issues and limitations

  • It is not possible to set global keyboard shortcuts for actions.
  • Subdocks disappear when an app is activated (this is a limitation of using xdg-popups; seems not the be an issue on KWin).
  • "Keep the dock below" option is buggy on older KWin (at least version 5.24). Works well on recent versions (tested on version 6.4.1).
  • Multi-monitor support is limited: docks can be placed only on a single screen.
  • Tracking virtual desktops / workspaces: displayed layout can be wrong (KWin).
  • Tracking virtual desktops / workspaces: only one "workspace group" is supported, with multiple monitors, not all workspaces will be tracked (Cosmic / Labwc).
  • Cosmic: tracking window positions across multiple monitors is buggy.
  • EGL rendering under Wayland relies on an officially unsupported interface in GTK (i.e. it uses gtk_widget_set_double_buffered() which is only supported on X11); in practice it works well at least with GTK versions 3.22.30 -- 3.24.41 on recent versions of all compositors tested.
  • EGL / OpenGL does not work very old KWin versions (5.20). An error message complains about some layer-shell surfaces having a zero size set; this might be related to the above point. Run the dock with the -c switch.
  • Placement of desklets does not work; desklets behave as regular windows and need to be positioned manually (see below for an example).

Positioning desklets

This requires either manually setting a position, or setting up a "window rule" if your compositor has such a functionality. E.g. on Wayfire, you can use the window-rules plugin to set a default position for desklets and also to keep them on top (or below). E.g. to set a specific position for the "clock" plugin, add the following to the [window-rules] section of your wayfire.ini configuration:

cd_clock = on created if title is "cairo-dock-desklet-clock" then move 1100 40

Note: the window title of any desklet will start with "cairo-dock-desklet-" followed by the plugin name. This only set an initial position; you can still move the desklet to a new position by dragging it afterwards.

To make all desklets appear always on top and sticky (appear on all workspaces), add the following:

cd_desklet_on_top = on created if title contains "cairo-dock-desklet" then set always_on_top
cd_desklet_sticky = on created if title contains "cairo-dock-desklet" then set sticky

Supporting other compositors

For full functionality, Cairo-Dock requires support for two main features in a compositor:

  • window positioning
  • information on currently running apps

While these were available by default to any app on X11, this is not the case on Wayland (due to core design decisions to better separate running apps from each other). Individual compositors might provide these as specific extensions (custom protocols) or plugins. To provide a reasonable user experience in Cairo-Dock, some form of support from the compositor side for these will be necessary.

Window positioning

Currently, Cairo-Dock uses the layer-shell protocol, which is created to provide desktop shell functionality and is emerging as a standard for this purpose (see here for explicit standardization efforts). Layer-shell is based on the concept that the compositor works together with a client app (such as Cairo-Dock) to determine its position. However, this is not a strict requirement. An alternative could be a compositor automatically positioning docks without any involvement on the Cairo-Dock side. Several compositors already provide this kind of functionality, such as a "window rules" option or similar (or such functionality can be easily added as a plugin / addon).

Taskbar

Currently, Cairo-Dock needs to receive info about running apps from the compositor, and supports several protocols for this purpose. Adding support for additional compositors that use their custom protocol would be relatively easy. Similarly, some other IPC method could be used and will be considered as necessary. For a compositor that currently does not support any such method, writing an extension or plugin would be necessary of course. An alternative is to use Cairo-Dock's DBus interface to add icons that represent running apps. However, this would require at least some modifications to how the DBus interface works and of course a matching IPC plugin on the compositor side.

Add a custom footer
Add a custom sidebar
Clone this wiki locally