Skip to main content
Most customization happens in Ryoku Settings (the Hub), opened with Mod+,. This page is the other half: the plain files Ryoku reserves for you in ~/.config/, which ryoku update never touches. Reach for them when the GUI does not cover what you want, or when you would rather edit text than click.

Settings (the GUI)

Appearance, displays, input, keybinds, the shell, and more, applied live.

Theming

Full-system themes, the wallust palette, and wallpapers.
Displays have both paths: tune them in Settings > Displays (see Displays & hardware), and hand-pin the stubborn ones in monitors_user.lua, below.

​
Personal Hyprland overrides: user.lua

~/.config/hypr/user.lua is yours. It is never shipped and never touched by ryoku materialize, and it loads last in the Hyprland config, so it wins over both the shipped defaults and anything Ryoku Settings writes. The load order, from ryoku/hyprland/hyprland.lua, is:
  1. modules.env, keyboard.lua.
  2. Generated drop-ins gpu.lua and monitors.lua (and your monitors_user.lua if present).
  3. The base modules (displays, input, decoration, animations, binds, resize, ryoshot, window_rules, fullscreen, autostart).
  4. The active theme (selected in Settings).
  5. settings.lua (written by the Hub).
  6. user.lua (yours, loaded last, wins).
Use the hl API the modules use (hl.bind, hl.windowrule, the keyword setters); do not shell out to hyprctl from Lua when an hl call exists.

​
Manual monitor pinning: monitors_user.lua

For everyday display changes, use Settings > Displays (see Displays & hardware). It writes the generated ~/.config/hypr/monitors.lua, which ryoku-monitor also rewrites once per machine and on hotplug or GPU reset. When you need a layout the panel cannot express, a fake-EDID display that needs a forced mode, a forced modeline, or a specific position, write ~/.config/hypr/monitors_user.lua instead. It loads after the generated file, so your pins win, and updates never touch it. A template ships at ~/.config/hypr/monitors_user.lua.example.

​
Per-app settings

Each app under ryoku/apps/<app>/ keeps its native format under its own directory; there is no Lua wrapper for a tool that reads its own config. Where an app ships a base file, drop your changes in the paired override file so an update cannot clobber them:

​
What survives an update

ryoku materialize clobbers the files Ryoku ships and prunes files a past release shipped but this one dropped. It never touches files Ryoku never shipped, which is what makes user.lua, monitors_user.lua, kitty/user.conf, fish/user.fish, and your own additions survive every update. The generated drop-ins (hypr/monitors.lua, hypr/gpu.lua) are seeded only when absent and are never clobbered or pruned, so an update never resets your display layout or GPU pin.
Editing a shipped file in place (anything in the “shipped file” column above, or hypr/hypridle.conf, and the other base configs) is reset on the next ryoku materialize. Put lasting changes in an override file, or in user.lua.

​
Reloading after a change

After editing a file by hand:
This restarts the shell and reloads Hyprland. Ryoku Settings applies its own changes live and does not need a reload.

​
See also

Settings

The GUI for everything above, and the panels this page complements.

Theming

Themes, palette, and wallpapers.

Displays & hardware

The GUI display, GPU, input, and power controls.

Keybindings

The shipped binds user.lua can override.
Last modified on July 4, 2026