Skip to content

Compatibility

Jump to bottom
Bobby Comet edited this page Aug 1, 2026 · 6 revisions

Compatibility

Conky Studio designs and exports real Conky themes. Compatibility is mostly Conky + your display session, not a separate Studio runtime after export.

The app detects your environment (Tools → Hardware & Session), resolves Canvas window_type = auto to a concrete Conky own_window_type, and warns in the UI and in generated config comments when desktop overlays are unlikely to work. Live Preview and Manager Start run the real Conky binary against real files — not a simulated canvas inside Qt.

For install packages and optional tools, see Requirements.

What Studio does for your environment

Studio does Studio cannot
Detect X11 vs Wayland (XDG_SESSION_TYPE, WAYLAND_DISPLAY, DISPLAY) Add layer-shell support to Mutter (GNOME)
Guess DE / compositor from XDG_CURRENT_DESKTOP / DESKTOP_SESSION Make an X11-only Conky package speak native Wayland
Report severity: ok / warn / block with concrete guidance Guarantee identical layering on every compositor
Resolve Canvas window_type → auto to a safe default (usually normal) Override compositor policy for always-on-top / click-through
Preflight before Live Preview / Start (“Start anyway” when blocked) Fix missing system tools (sensors, playerctl, GPU)
Generate relocatable start.sh + conky.conf + render.lua Change how Mutter treats overlay clients
Annotate known Conky log lines with extra hints

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.

Quick matrix

Environment Desktop HUD overlays Notes
X11 (any DE) Best Most predictable for Conky
Plasma Wayland + Wayland-enabled Conky Good Supported path
Sway / Hyprland / Wayfire / labwc / river / niri (+ 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, Openbox, and similar.
  • Recommended baseline when something looks blank or mis-layered on Wayland.
  • Studio resolves window_type = auto → normal with standard undecorated / below / sticky / skip-taskbar / skip-pager hints.

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:

conky -v

If the output does not mention Wayland, the package is likely X11-only. Themes may only work under XWayland or may not anchor correctly. Fix: install or build Conky with Wayland enabled. Studio’s Hardware report flags this as warn.

Wayland compositors Studio treats as likely supported

Detector matches tokens in XDG_CURRENT_DESKTOP / DESKTOP_SESSION (case-insensitive substrings), including:

Compositor / stack Status
Sway Supported target
Hyprland Supported target
Wayfire Supported target
labwc Supported target
river Supported target
niri, mangowc, waybox, other wlroots-based Same protocol family; often work
KDE Plasma (Wayland) Supported (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 inside the Studio window.

On Plasma Wayland, auto window type stays normal (validated path; some Plasma versions hide desktop-type windows on desktop click).

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. Severity is block.
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.

How generated themes behave

Built themes are ordinary folders (e.g. ~/.config/conky/MyHUD/):

File Role
start.sh Single-instance lock, optional daemon pollers, then exec conky -c conky.conf
conky.conf Window type/hints from Studio’s session resolve; empty conky.text; Lua draw hook
render.lua Framework + your node graph (Cairo)
scripts/, images/, theme.json Polling scripts, assets, metadata

After install, Conky Studio is not required. The same session rules apply on every machine that runs the theme.

Drawing uses conky_surface() when available (X11 and Wayland-capable builds), with a correct fallback to the older xlib surface path so surface ownership does not segfault.

Hardware & related tools

Component Impact if missing
lm-sensors CPU/board temps blank until install + sensors-detect
GPU tools / drivers NVIDIA/AMD/Intel sources may read 0
Network interface Wrong or missing iface → zero traffic stats (auto-detect helps)
playerctl Music / now-playing empty
curl Weather / public IP fail
Fonts Fallback typefaces; install on the target PC (Tools → Install Font helps while authoring)

See Requirements for package names per distro.

Sharing themes across machines

Share Depends on
Built theme folder Recipient’s Conky + session (same rules as above). No Studio required.
Project JSON (.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?, severity
  2. conky -v — is Wayland listed when you are on Wayland?
  3. Try an X11 session if overlays fail on Wayland
  4. 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

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 the environment, chooses safe window defaults, and warns; it does not replace Conky’s display backends or compositor protocols.

See also Requirements.

Clone this wiki locally