Convert windowrulev2 and layerrule lines into hl.window_rule and hl.layer_rule
Nearly every claim holds against the v0.56.2 source. hlWindowRule skips name, enabled and match, and reports any other key that is neither a static nor a dynamic effect as 'hl.window_rule: unknown field', with addError rather than a Lua error, so loading continues. Unknown match keys give 'unknown match property'. IRule::canMatch() requires a non-empty matcher set. CRegexMatchEngine uses RE2::FullMatch and honours the 'negative:' prefix. All nineteen renamed effects in the cause exist in WINDOW_RULE_EFFECT_DESCS, there is no no_border or no_rounding, and the matcher names match MATCH_PROP_STRINGS. hl.layer_rule accepts namespace as a matcher and blur as an effect. Lua 5.5.1 here reproduces both quoted parse errors exactly. On Omarchy 4.0.4-1, o.window in helpers.lua builds the match table as described, and default/hypr/apps/system.lua gives the floating-window tag float, center and 875x600. The wiki window-rules page confirms static effects are evaluated once when the window opens. The one defect was in the fix: the Picture-in-Picture example converts a single 'float' line but adds pin = true with no hyprlang line for it, so the comment and the code disagree. The fix now shows the matching pin line. No rule was exercised live.
Symptom
After moving to the Lua config my window rules are dead: pavucontrol and file pickers open tiled, nothing goes to its workspace, opacity rules are gone. Pasting the old lines gives <name> expected near '^' (windowrulev2 = float, class:^(pavucontrol)$) or function arguments expected near 'pavucontrol' (the 0.53 form windowrule = match:class pavucontrol, float on). After a first attempt at Lua the error list shows hl.window_rule: unknown field 'class', hl.window_rule: unknown field 'noblur' or hl.window_rule: unknown match property 'initialClass', and the rule still does nothing.
Cause
Hyprland 0.55 moved rules to Lua tables: hl.window_rule({ match = { ... }, <effect> = <value> }) and hl.layer_rule with the same shape. Three things differ from hyprlang.
- Matchers must sit inside the
matchtable. In Hyprland 0.56.2 (hlWindowRuleinsrc/config/lua/bindings/LuaBindingsConfigRules.cpp) any top-level key that is notname,enabled,matchor a known effect is reported asunknown field '<key>'and skipped. A rule with no match entries never applies at all, becauseIRule::canMatch()insrc/desktop/rule/Rule.cpprequires at least one matcher. Sohl.window_rule({ class = "pavucontrol", float = true })floats nothing. - Matcher and effect names are snake_case. The pre-0.53 effect names
noblur,noshadow,nofocus,noanim,idleinhibit,stayfocused,noinitialfocus,bordersize,bordercolor,dimaround,keepaspectratio,noscreenshare,suppressevent,persistentsize,allowsinput,nomaxsize,renderunfocused,minsize,maxsizebecameno_blur,no_shadow,no_focus,no_anim,idle_inhibit,stay_focused,no_initial_focus,border_size,border_color,dim_around,keep_aspect_ratio,no_screen_share,suppress_event,persistent_size,allows_input,no_max_size,render_unfocused,min_size,max_size.noborderandnoroundinghave no effect of their own: useborder_size = 0androunding = 0. Matchers areclass,title,initial_class,initial_title,xwayland,float,fullscreen,pin,focus,group,modal,tag,workspace,content,xdg_tagand a few more, notinitialClassorfloating. - Values are Lua values. Boolean effects take
true, sizes take{ 800, 600 }, and string arguments such asworkspace = "3 silent"oropacity = "0.9 0.8"are quoted. Class and title are matched with RE2FullMatch, soclass = "firefox"already means the whole class, and thenegative:prefix still works inside the string.
Each bad key is a type error, which Hyprland reports and then keeps loading, so the rest of the file still applies and only the broken rule silently does less than it should.
Fix
**Find the window's real class first**, because a wrong class is the other common reason a rule never fires:
hyprctl clients | grep -E '^Window|class:|title:'
**Convert.** On Omarchy 4 put rules in ~/.config/hypr/hyprland.lua below require("default.hypr.toggles"), or in any ~/.config/hypr/*.lua it requires. They load after Omarchy's own rules and the last match wins. On plain Arch put them in ~/.config/hypr/hyprland.lua.
-- windowrulev2 = float, class:^(pavucontrol)$
-- windowrulev2 = size 800 600, class:^(pavucontrol)$
-- windowrulev2 = center, class:^(pavucontrol)$
hl.window_rule({
match = { class = "^(pavucontrol|org.pulseaudio.pavucontrol)$" },
float = true,
size = { 800, 600 },
center = true,
})
-- windowrulev2 = workspace 3 silent, class:^(discord)$
hl.window_rule({ match = { class = "^(discord)$" }, workspace = "3 silent" })
-- windowrulev2 = opacity 0.9 0.8, class:^(code)$
-- windowrulev2 = noblur, class:^(code)$
hl.window_rule({ match = { class = "^(code)$" }, opacity = "0.9 0.8", no_blur = true })
-- windowrulev2 = idleinhibit fullscreen, class:.*
hl.window_rule({ match = { class = ".*" }, idle_inhibit = "fullscreen" })
-- windowrulev2 = float, class:^(firefox)$, title:^(Picture-in-Picture)$
-- windowrulev2 = pin, class:^(firefox)$, title:^(Picture-in-Picture)$
hl.window_rule({ match = { class = "^(firefox)$", title = "^(Picture-in-Picture)$" }, float = true, pin = true })
-- layerrule = blur, waybar
hl.layer_rule({ match = { namespace = "waybar" }, blur = true })
**Omarchy 4 shortcuts.** o.window(match, effects) from /usr/share/omarchy/default/hypr/helpers.lua builds the match table for you, where a string means the class:
o.window("^(pavucontrol)$", { float = true })
o.window({ class = "^(firefox)$", title = "^(Picture-in-Picture)$" }, { float = true, pin = true })
-- Omarchy's own float + center + 875x600 treatment, defined in default/hypr/apps/system.lua:
o.window("^(pavucontrol)$", { tag = "+floating-window" })
The effect list for 0.56 is on the wiki window-rules page. A static effect such as float, size or workspace is applied once at window creation against the initial class and title, so it cannot react to a later title change.
Verify
hyprctl configerrors lists no hl.window_rule or hl.layer_rule lines. Open the app again (static effects only apply to new windows) and check hyprctl clients: the window shows floating: 1, the expected workspace:, or the tag (floating-window*) in tags:. Field names and the empty-match behaviour were read from the Hyprland 0.56.2 source. No rule was exercised live.
Sources
- https://wiki.hypr.land/configuring/core/rules/window-rules/
- https://github.com/hyprwm/hyprland-wiki/blob/main/content/configuring/core/rules/layer-rules.md
- https://wiki.hypr.land/0.52.0/Configuring/Window-Rules/
- https://wiki.hypr.land/0.54.0/Configuring/Window-Rules/
- https://github.com/hyprwm/Hyprland/blob/v0.56.2/src/config/lua/bindings/LuaBindingsConfigRules.cpp
- https://github.com/hyprwm/Hyprland/blob/v0.56.2/src/desktop/rule/Rule.cpp
- https://github.com/hyprwm/Hyprland/blob/v0.56.2/src/desktop/rule/matchEngine/RegexMatchEngine.cpp
- https://github.com/omacom/omarchy/blob/quattro/default/hypr/helpers.lua
- https://github.com/omacom/omarchy/blob/quattro/default/hypr/apps/system.lua