server-desktop-01/docs/hyprland/version-history.md

Hyprland Version History — Breaking Config Changes

Focus: syntax changes that affect our config. Not a full changelog.

Installed: 0.51.1 (Sept 2025)

windowrule syntax timeline

Pre-0.48 (old — do not use)

windowrule = float, ^(class-regex)$           # v1: positional class, no prefix
windowrulev2 = float, class:^(regex)$         # v2: explicit class: prefix

0.48–0.51 (CURRENT — use this)

Both windowrule and windowrulev2 keywords work, but windowrulev2 is deprecated. Use windowrule with match: prefixed props. Patterns are plain strings or bare regexes — do NOT use the old rulev2 ^(...)$ wrapping; Hyprland 0.51 rejects it as "Invalid rulev2".

windowrule = match:class classname, effect
windowrule = match:class classname, match:title titlepattern, effect1, effect2
windowrule = match:class ^org\.gnome\., rounding 12   # prefix regex — anchor ok, no outer ()

Props can come in any order relative to effects. Boolean effects: float, tile, pin, no_initial_focus (no "on" suffix needed) Value effects: rounding 12, opacity 0.9

0.52+ (not yet installed — do not use until upgrade)

Block syntax introduced:

windowrule {
    name = optional-name
    match:class = ^(regex)$
    float = yes
    rounding = 12
}

Anonymous flat block syntax also available:

windowrule = match:class regex, effect value

layerrule syntax timeline

Pre-0.48 (old)

layerrule = no_anim, ^(namespace)$   # positional namespace

0.48–0.51 (CURRENT — use this)

layerrule = match:namespace namespacename, no_anim

Same rule as windowrule: plain string or bare regex, no ^(...)$ wrapping.

0.52+ (block syntax)

layerrule {
    match:namespace = ^(regex)$
    no_anim = on
}

Other notable changes

Version	Change
0.48	windowrulev2 deprecated; new windowrule with match: prefix
0.48	layerrule updated to use match:namespace prefix
0.52+	Block syntax for windowrule and layerrule

Upgrade checklist

When upgrading Hyprland:

1. Check hyprland --version (or rpm -q hyprland)
2. Scan release notes for "windowrule", "layerrule", "deprecated"
3. Update this file
4. Update the comment in hyprland.conf window rules section