Skip to content

Compatibility

Jump to bottom
Bobby Comet edited this page Aug 6, 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 installing packages and optional tools, see Requirements.

On X11:

  • normal, desktop, dock → predictable-ish

On Wayland:

  • These are intent hints, not guarantees
  • wlroots respects them via layer-shell
  • KDE kinda maps them
  • GNOME ignores half of it

Your window_type="desktop" is not a contract; it’s a best-effort strategy

Live Preview uses normal window mode intentionally. Final exported themes may behave differently depending on your compositor.

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 mislayered 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 for 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 to 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