Skip to content

Compatibility

Jump to bottom
Bobby Comet edited this page Jul 31, 2026 · 6 revisions

Compatibility

Conky Studio designs and exports real Conky themes. Compatibility is mostly Conky + your display session, not a separate Studio runtime. Studio detects your environment (Tools → Hardware & Session) and warns when overlays are unlikely to work.

Quick matrix

Environment Desktop HUD overlays Notes
X11 (any DE) Best Most predictable for Conky
Plasma Wayland + Wayland Conky Good Supported path; occasional Wayland-specific quirks
Sway / Hyprland / Wayfire / labwc / river (+ other wlroots) + Wayland Conky Good Layer-shell compositors
Mir-based Wayland + Wayland Conky Expected Same class as layer-shell targets
GNOME Wayland (Mutter) No overlays Mutter does not provide the protocol Conky needs
Wayland + X11-only Conky package Poor / unreliable Install or build a Wayland-enabled Conky

Display servers

X11

  • Broadest compatibility for classic Conky HUDs (own window, transparency, below-desktop behaviour).
  • Works across GNOME-on-Xorg (where still offered), Plasma X11, XFCE, MATE, Cinnamon, i3, and similar.
  • Recommended baseline when something looks blank or mis-layered on Wayland.

Wayland

Wayland is a protocol; each compositor decides what overlays can do. Conky draws as a desktop HUD on Wayland primarily via wlr-layer-shell (layer-shell). Without that, Conky cannot act as a background/panel-style overlay.

You also need a Conky binary built with Wayland support. Check:

conky -v

If the output does not mention Wayland, the package is likely X11-only (common on some Ubuntu/Debian builds historically). Themes may only work under XWayland or may not anchor correctly. Fix: install/build Conky with Wayland enabled.

Wayland compositors Studio treats as likely supported

These match Conky’s documented layer-shell targets. Studio’s detector looks for names in XDG_CURRENT_DESKTOP / DESKTOP_SESSION:

Compositor / stack Status
Sway Supported target
Hyprland Supported target
Wayfire Supported target
labwc Supported target
river Supported target
Other wlroots-based compositors Same protocol family; often work even if not named in the short list
KDE Plasma (Wayland) Supported target (kde, plasma, kde-plasma)
Mir-based Expected supported target

Requirements on these sessions:

  1. Wayland-enabled Conky (conky -v shows Wayland)
  2. Layer-shell available from the compositor
  3. Sensible Canvas size, alignment, and gaps in the project

Live Preview and built themes use a real Conky window (own_window / layer-shell), not an embedded foreign surface.

Not supported for desktop overlays

Stack Why
GNOME (Mutter) on Wayland Mutter does not implement wlr-layer-shell for this use case. Conky cannot run as a desktop overlay here. This is a compositor limitation, not a missing Studio setting.
Typical Ubuntu GNOME Wayland Same Mutter limitation

Options on GNOME-oriented systems:

  • Use a GNOME on Xorg session if the distro still offers one
  • Use Plasma, Sway, Hyprland, or another layer-shell compositor
  • Do not expect Studio config tweaks (own_window_type, etc.) to unlock Mutter overlays

As more stacks move Wayland-only, the GNOME gap matters more for Conky users; Studio can only detect and warn.

What Studio configures vs what it cannot fix

Studio can Studio cannot
Detect X11 vs Wayland Add layer-shell to Mutter
Detect likely DE / compositor family Make an X11-only Conky package speak native Wayland
Warn in Hardware & Session and in generated conf comments Guarantee pixel-identical behaviour on every compositor
Resolve Canvas window_type auto → a concrete own_window_type (default safe: normal) Override compositor policy for always-on-top / click-through / desktop layering
Generate standard start.sh + conf + Lua Fix missing system tools (playerctl, sensors, GPU tools)

On Wayland, classic X11 window hints have limited effect once layer-shell owns the surface. Prefer fixing session + Conky build over endless own_window_* experiments on unsupported compositors.

Hardware & related tools

Component Impact
lm-sensors CPU/board temps; blank without install + detect
GPU tools / drivers NVIDIA/AMD/Intel sources may read 0 if undetectable
Network interface name Wrong iface → zero traffic stats
playerctl Music / now-playing nodes
Fonts Theme fonts must exist on the target machine (Tools → Install Font helps on the author PC)

Sharing themes across machines

Share Depends on
Built theme folder Recipient’s Conky + session (same rules as above). No Studio required.
Project JSON Same session rules plus matching Studio version, plugins, and asset paths

A theme that works on Hyprland may still fail on GNOME Wayland on another PC — that is expected.

Checklist when something is blank

  1. Tools → Hardware & Session — display server, desktop, layer-shell likely?, Conky Wayland build?
  2. conky -v — is Wayland listed?
  3. X11 vs Wayland — try an X11 session if overlays fail on Wayland
  4. DE — avoid expecting overlays on GNOME Wayland
  5. Run the theme’s ./start.sh in a terminal and read errors
  6. Minimal graph (one Text constant) — if that fails, the session/Conky install is the problem, not the node graph

See also Troubleshooting and Troubleshooting Themes.

Summary

  • Best overall: X11.
  • Wayland HUDs: Plasma Wayland and wlroots compositors (Sway, Hyprland, Wayfire, labwc, river, …) with a Wayland-built Conky.
  • Not for overlays: GNOME Mutter Wayland.
  • Studio detects and warns; it does not replace Conky’s display backends or compositor protocols.

Clone this wiki locally