1 +#
Hypr ecosystem tools 3 -First-party Hypr apps are version-sensitive.
4 -Check installed tool help and current Hypr wiki before copying config.
3 +Official Hypr ecosystem docs target latest `-git`.
4 +Installed distro packages may lag.
5 +For exact local behavior, check installed binaries, packaged unit files, and
6 +current wiki source before editing.
8 +Keep this guidance general-purpose.
9 +Do not encode one user's rice, monitor names, wallpaper paths, services, or
10 +theme choices in this skill.
6 12 ##
User apps/utilities 8 -| Tool | Role | Overlaps |
9 -| ----------------------------- | ----------------------- | --------------------------------------------------------- |
10 -| `hyprpaper` | wallpaper daemon | swaybg, wpaperd, swww/awww, mpvpaper |
11 -| `hyprpicker` | screen color picker | wl-color-picker, grim/slurp picker scripts |
12 -| `hyprlauncher` | launcher/picker | fuzzel, walker, rofi-wayland, wofi, tofi, anyrun |
13 -| `hypridle` | idle daemon | swayidle |
14 -| `hyprlock` | lock screen | swaylock, gtklock |
15 -| `xdg-desktop-portal-hyprland` | portal backend | required for Hyprland screencast/global-shortcut features |
16 -| `hyprsysteminfo` | system info GUI | fastfetch, inxi frontends |
17 -| `hyprsunset` | blue-light/gamma | wlsunset, gammastep, compositor shaders |
18 -| `hyprpolkitagent` | polkit auth agent | polkit-kde-agent, GNOME polkit agent |
19 -| `hyprpwcenter` | PipeWire control center | pavucontrol, pwvucontrol, other audio GUIs |
20 -| `hyprshutdown` | graceful shutdown UI | wlogout, rofi/quickshell power menus |
21 -| `hyprland-qt-support` | Qt/Hypr integration | qt platform/theme glue |
22 -| `hyprqt6engine` | Qt6 theme engine | qt6ct, Kvantum, KDE color scheme tooling |
14 +| Tool | Role | Config path | Runtime/startup |
15 +| ----------------------------- | ----------------------- | ------------------------------------------------ | --------------------------------------------------- |
16 +| `hyprpaper` | wallpaper daemon | `~/.config/hypr/hyprpaper.conf` optional | `hyprpaper` or packaged `hyprpaper.service` |
17 +| `hyprpicker` | color picker | none | one-shot CLI flags |
18 +| `hyprlauncher` | launcher/picker | `~/.config/hypr/hyprlauncher.conf` optional | bind `hyprlauncher`; it manages its own daemon |
19 +| `hypridle` | idle daemon | `~/.config/hypr/hypridle.conf` required | `hypridle` or packaged `hypridle.service` |
20 +| `hyprlock` | lock screen | `~/.config/hypr/hyprlock.conf` required | one-shot `hyprlock`; often called by hypridle |
21 +| `xdg-desktop-portal-hyprland` | portal backend | `~/.config/hypr/xdph.conf` optional | D-Bus autostart; do not normally autostart manually |
22 +| `hyprsysteminfo` | system info GUI | none | one-shot GUI |
23 +| `hyprsunset` | blue-light/gamma daemon | `~/.config/hypr/hyprsunset.conf` optional | `hyprsunset` or packaged `hyprsunset.service` |
24 +| `hyprpolkitagent` | polkit auth agent | none | packaged service or session autostart |
25 +| `hyprland-qt-support` | QML style for hypr apps | `~/.config/hypr/application-style.conf` optional | loaded by supported Qt/QML Hypr apps |
26 +| `hyprqt6engine` | Qt6 platform theme | `~/.config/hypr/hyprqt6engine.conf` optional | set `QT_QPA_PLATFORMTHEME=hyprqt6engine` |
27 +| `hyprpwcenter` | PipeWire GUI | none documented | one-shot GUI |
28 +| `hyprshutdown` | graceful Hyprland exit | none documented | bind `hyprshutdown` |
27 -| --------------------- | -------------------------------------------------- |
28 -| `hyprtoolkit` | C++ GUI toolkit for native Wayland apps |
29 -| `hyprcursor` | Hypr cursor theme format/support |
30 -| `hyprutils` | shared utility library |
31 -| `hyprlang` | legacy Hypr config language/parser library |
32 -| `hyprwayland-scanner` | Wayland protocol source/header generator |
33 -| `aquamarine` | rendering/backend library |
34 -| `hyprgraphics` | graphics utility library |
35 -| `hyprland-guiutils` | GUI utility helpers/successor area for old qtutils |
32 +- If docs/package ships a user unit, prefer that unit over custom copies:
33 + `systemctl --user cat hyprpaper.service` etc.
34 +- Packaged user units commonly exist for `hyprpaper`, `hypridle`, `hyprsunset`,
36 + Verify before assuming.
37 +- Under UWSM/user-service setups, use `systemctl --user enable --now
39 +- Otherwise preserve compositor autostart style, e.g. `hl.exec_cmd("hypridle")`.
40 +- Do not create custom `ExecStartPost` wallpaper/theme hacks unless explicitly
42 +- Do not start competing daemons silently.
43 + State replacements first.
44 +- Do not manually autostart XDPH in normal setups; D-Bus starts it.
37 -Dev libs matter for packaging/plugins/build errors, not normal desktop config.
39 -##
No first-party Hypr tool exists 48 +Docs state hyprlauncher is always a daemon internally.
49 +Simplest correct setup:
41 -| Role | Default primitive | Higher-level choices |
42 -| ----------------- | ------------------------------- | ------------------------------------------------------ |
43 -| notifications | FreeDesktop notification daemon | mako=minimal, swaync=center, dunst/fnott |
44 -| screenshots | grim + slurp + wl-clipboard | hyprshot/HyprCapture wrappers, satty/swappy annotation |
45 -| screen recording | PipeWire/portal or wf-recorder | OBS, wl-screenrec |
46 -| clipboard history | wl-clipboard primitive | cliphist, CopyQ Wayland mode |
47 -| status bar/shell | layer-shell client | Waybar, ashell, Quickshell, AGS/Astal, Eww |
52 +hl.bind("SUPER + Space", hl.dsp.exec_cmd("hyprlauncher"), { description = "launcher" })
49 -Prefer first-party only where it exists and fits.
50 -Do not invent Hypr-native ownership for generic Wayland roles.
57 +- No wrapper needed for normal use.
58 +- No autostart needed for normal use.
59 +- `hyprlauncher -d` starts daemon without opening; only use for intentional warm
62 + feed stdin to `hyprlauncher --dmenu`.
64 + `~/.config/hypr/hyprlauncher.conf`.
65 +- Theme comes from `hyprtoolkit`.
67 +Key config categories/options:
70 +general:grab_focus = true
72 +finders:default_finder = desktop
73 +finders:desktop_launch_prefix =
74 +finders:desktop_icons = true
75 +ui:window_size = 400 260
80 +Current wiki syntax uses anonymous `wallpaper { ...
81 +}` blocks, not old `preload = ...` + `wallpaper = MON,PATH` lines.
86 + path = ~/wallpapers/fallback.png
97 + `~/.config/hypr/hyprpaper.conf`; optional.
98 +- `monitor =` may be empty → fallback wallpaper.
99 +- `path = ~/...` is valid; do not expand to `/home/...` just to appease parser.
101 + `contain` | `cover` | `tile` | `fill`; default `cover`.
102 +- Directory `path` may use `timeout`, `order = random`, `recursive`.
103 +- `source = ~/.config/hypr/hyprpaper.d/*.conf` supports globbing, tilde
104 + expansion, relative paths; parse order is linear.
106 + `hyprctl hyprpaper wallpaper '[mon], [path], [fit_mode]'`; `mon` may be empty
107 + for fallback, fit mode optional.
111 +Config is required; daemon exits without one.
115 + lock_cmd = pidof hyprlock || hyprlock
116 + before_sleep_cmd = loginctl lock-session
117 + after_sleep_cmd = hyprctl dispatch dpms on
122 + on-timeout = loginctl lock-session
129 + `~/.config/hypr/hypridle.conf`.
130 +- `general` covers D-Bus lock/unlock, sleep hooks, inhibitor behavior.
131 +- `listener` blocks define `timeout`, `on-timeout`, `on-resume`,
133 +- Common safe pattern:
134 + `lock_cmd = pidof hyprlock || hyprlock`.
136 + prefer `before_sleep_cmd = loginctl lock-session`.
137 +- `inhibit_sleep` default is auto; do not override without reason.
142 +If no config is found, hyprlock exits and the session is not locked.
146 +1. `$XDG_CONFIG_HOME/hypr/hyprlock.conf`
147 +2. `$HOME/.config/hypr/hyprlock.conf`
148 +3. `$XDG_CONFIG_DIRS/*/hypr/hyprlock.conf`
149 +4. `/etc/xdg/hypr/hyprlock.conf`
175 +- `monitor =` empty means all monitors for widgets.
176 +- Widget positioning uses `halign`, `valign`, `position`, `zindex`.
177 +- `background:path = screenshot` is supported.
178 +- Labels/images can run commands; never use non-exiting commands.
180 + `pkill -USR1 hyprlock` unlocks; mention before risky lock edits.
181 +- Locked Hyprland binds need lock flag (`l`) to work while locked.
185 +Config optional but recommended for scheduled profiles.
205 + `~/.config/hypr/hyprsunset.conf`.
206 +- Supported since Hyprland 0.45.0.
207 +- Profiles activate by clock time; startup applies current profile.
208 +- `identity = true` disables color-temperature shift while allowing gamma.
210 + - `hyprctl hyprsunset temperature 2500`
211 + - `hyprctl hyprsunset identity`
212 + - `hyprctl hyprsunset gamma 50` or `+10`/`-10`
213 + - `hyprctl hyprsunset reset [temperature|gamma|identity]`
214 +- Gamma degrades color accuracy; prefer real brightness controls if available.
216 +##
`hyprpolkitagent` 218 +Polkit auth agent; required for GUI elevation prompts.
219 +No config documented.
223 +- Prefer packaged `hyprpolkitagent.service` under UWSM/user services.
224 +- Otherwise autostart `systemctl --user start hyprpolkitagent` or the binary.
225 +- Binary path varies by distro:
226 + `/usr/lib/hyprpolkitagent/hyprpolkitagent`, `/usr/libexec/hyprpolkitagent`,
227 + `/usr/lib64/libexec/hyprpolkitagent`.
228 +- Only one polkit agent should run.
232 +No config; launch with flags.
237 +hyprpicker --autocopy
238 +hyprpicker --autocopy --format rgb
239 +hyprpicker --notify --lowercase-hex
243 +`--format cmyk|hex|rgb|hsl|hsv`, `--output-format`, `--no-zoom`,
244 +`--render-inactive`, `--scale`, `--radius`, `--quiet`.
248 +Graceful Hyprland exit UI.
249 +Recommended over raw compositor exit when apps should close cleanly.
252 +hl.bind("SUPER + SHIFT + Q", hl.dsp.exec_cmd("hyprshutdown"), { description = "power" })
259 +- `--top-label` / `-t`
260 +- `--post-cmd` / `-p` for shutdown/reboot after Hyprland exits
261 +- `--vt N` for NVIDIA+SDDM VT handoff issues
262 +- `--no-fork`, `--verbose`
264 +Do not add passwordless `chvt` sudo rules without explicit user approval.
266 +##
XDPH (`xdg-desktop-portal-hyprland`) 268 +Provides screenshare/global-shortcut portals.
269 +Does not implement file picker; install GTK/KDE portal as fallback.
273 +- D-Bus starts XDPH when needed; do not normally autostart/kill-loop it.
275 + `~/.config/hypr/xdph.conf`.
281 + allow_token_by_default = false
282 + custom_picker_binary = hyprland-share-picker
288 + `systemctl --user status xdg-desktop-portal-hyprland xdg-desktop-portal`.
289 +- For file picker preference, use
290 + `~/.config/xdg-desktop-portal/hyprland-portals.conf`, not `xdph.conf`.
292 +##
Hypr Qt/theme tools 296 +General toolkit theme config for Hypr ecosystem apps:
297 +`~/.config/hypr/hyprtoolkit.conf`.
300 +background = 0xFF181818
303 +alternate_base = 0xFF272727
304 +bright_text = 0xFFFFDEDE
306 +accent_secondary = 0xFF0099F0
307 +font_family = Sans Serif
308 +font_family_monospace = monospace
313 +Also supports `h1_size`, `h2_size`, `h3_size`, `font_size`, `small_font_size`,
316 +###
`hyprland-qt-support` 318 +QML style for hypr* Qt6 apps.
320 +`~/.config/hypr/application-style.conf`.
325 +reduce_motion = false
330 +Qt6 platform theme replacement for qt6ct.
331 +Use only if installed:
334 +hl.env("QT_QPA_PLATFORMTHEME", "hyprqt6engine")
338 +`~/.config/hypr/hyprqt6engine.conf`.
341 +theme:color_scheme =
343 +theme:style = Fusion
344 +theme:font = Sans Serif
345 +theme:font_size = 11
346 +theme:font_fixed = monospace
347 +theme:font_fixed_size = 11
348 +misc:single_click_activate = true
349 +misc:menus_have_icons = true
350 +misc:shortcuts_for_context_menus = true
353 +##
Other user utilities 356 + GUI to display/copy Hyprland/system info.
359 + PipeWire graph/control GUI.
360 + No config documented.
362 +##
Cursor/support/dev tools 365 + cursor theme format.
366 + Set `HYPRCURSOR_THEME` and `HYPRCURSOR_SIZE`; also set
367 + `XCURSOR_THEME`/`XCURSOR_SIZE` for apps that fall back to XCursor.
368 + Themes should live in `~/.local/share/icons` or `~/.icons`.
370 + config language/parser for hypr* apps.
371 + Supports categories, variables, comments with `#`, inline `category:option`,
372 + arithmetic `{{A + B}}`, and conditionals.
373 + App-specific keywords such as `source` vary by tool.
374 + Preserve syntax family.
375 +- `hyprutils`, `hyprgraphics`:
376 + shared libraries; no normal desktop config.
377 +- `hyprwayland-scanner`:
378 + C++ Wayland protocol code generator; dev only.
380 + rendering backend library; configured by env vars like `AQ_DRM_DEVICES`,
381 + `AQ_NO_MODIFIERS`, `AQ_NO_ATOMIC`.
382 + Use only for backend/GPU troubleshooting.
383 +- `hyprland-guiutils`:
384 + GUI utility helpers/successor area for old qtutils.
61 391 hyprlauncher --help
62 -systemctl --user status hyprpaper hypridle hyprsunset hyprpolkitagent
396 +systemctl --user cat hyprpaper hypridle hyprsunset hyprpolkitagent
397 +systemctl --user status hyprpaper hypridle hyprsunset hyprpolkitagent xdg-desktop-portal-hyprland xdg-desktop-portal
63 398 journalctl --user -b
| grep -Ei
'hyprpaper|hyprlock|hypridle|hyprsunset|polkit|xdg-desktop-portal' 68 -- Preserve the user's config format and module layout.
69 -- Do not start competing daemons silently.
70 -- State what each daemon replaces before enabling it.
71 -- Prefer `systemctl --user` units when the user's setup already uses user
72 - services; otherwise preserve compositor autostart style.
403 +- Preserve user's config format and module layout.
404 +- Remove wrappers/custom units when upstream docs/package provide a simple path.
405 +- Avoid configs for tools with no documented config.
406 +- Avoid absolute paths if docs support `~` or relative paths.
407 +- Never install/start competing daemons without saying what it replaces.
73 408 - For lock/idle changes, describe emergency unlock/recovery path first.