Scratchpads broken on Hyprland 0.53.0 due to windowrule syntax change

[bmethod]

Hyprland 0.53.0 completely overhauled the windowrule syntax. This breaks pyprland scratchpads because the old format is no longer valid.

Errors seen

FAILED b'invalid field float: missing a value'
FAILED b'invalid field unset: missing a value'
FAILED b'invalid field class:org.coolercontrol.CoolerControl: missing a value'

Cause

Pyprland sends the old syntax:

windowrule float,class:classname
windowrule workspace special:S-name silent,class:classname

Hyprland 0.53.0 requires:

windowrule match:class classname, float on
windowrule match:class classname, workspace special:S-name silent

Workaround

I've patched plugins/scratchpads/__init__.py locally with the following changes:

1. Added a new class decorator for 0.53.0+:

def class_decorator_053(name: str) -> str:
    """Return the class rule for hyprland 0.53.0+."""
    return f"match:class {name}"

2. Updated version detection in on_reload:

if state.hyprland_version >= VersionInfo(0, 53, 0):
    self._classify = class_decorator_053
    self._rule_format = "new"
elif state.hyprland_version > VersionInfo(0, 47, 2):
    self._classify = class_decorator_new
    self._rule_format = "old"
else:
    self._classify = class_decorator_old
    self._rule_format = "old"

3. Updated all windowrule constructions to swap the order for 0.53.0+:

# Old format
f"windowrule float,{self._classify(defined_class)}"
# New format  
f"windowrule {self._classify(defined_class)}, float on"

This applies to float, workspace, move, size, and unset rules.

Note: The unset rule still shows an error - I'm not certain of the correct 0.53.0 syntax for unsetting windowrules.

Environment

• Hyprland 0.53.0
• pyprland 2.5.1 (git)

Related

#191

[migueldamota]

@bmethod I also tried it with this syntax and then I switched to named windowrules but the problem with named windowrules is, they need to be defined before in a hyprland config. Therefore creating them dynamically is not working and unsetting AFAIK is replaced with enabled. At least I can't find anything else

[bmethod]

@migueldamota Yeah. I tested a few approaches..

• windowrule match:class X, unset on → "invalid field type unset"
• windowrule match:class X, enabled off → "invalid field type enabled"

The working solution (for now) is to simply skip the unset call entirely for 0.53.0+. The rules persist in memory but scratchpads still function since windows are moved to special workspaces on hide anyway.

  if getattr(self, '_rule_format', 'old') == "new":
    # Hyprland 0.53.0+ cannot unset anonymous rules dynamically
    return

Not ideal since rules accumulate, but functional. A proper fix would need pyprland to use named rules pre-defined in config.

[migueldamota]

So right now I have those in my hyprland.conf:

windowrule {
        name = scratchpad-termRight
        match:class = ghostty.term-right
}
windowrule {
        name = scratchpad-termLeft
        match:class = ghostty.term-left
}
windowrule {
        name = scratchpad-term
        match:class = ghostty.term-top
}

This is my pyprland.toml

pyprland]
plugins = [
    "scratchpads",
]

[scratchpads.term]
animation = "fromTop"
command = "ghostty --class=ghostty.term-top"
class = "ghostty.term-top"
size = "60% 50%"
max_size = "1920px 100%"
margin = 24

[scratchpads.termRight]
animation = "fromRight"
command = "ghostty --class=ghostty.term-right"
class = "ghostty.term-right"
size = "40% 90%"
max_size = "1920px 100%"
margin = 24

[scratchpads.termLeft]
animation = "fromLeft"
command = "ghostty --class=ghostty.term-left"
class = "ghostty.term-left"
size = "40% 90%"
max_size = "1920px 100%"
margin = 24

You can have a look at my "fix": migueldamota@aa06a7a

So the basic fix is, add the windowrules in a hyprland config, run hyprctl reload and then it should work with opening/toggling them

[peterjumper]

'windowrule' to 'windowrulev2' can fix my hypr config temporary

quick converter:

use this converter
source:https://forum.hypr.land/t/0-53-window-layerrule-converter/1243

Rule Converter

[fdev31]

Check the git version, it should support older and the newest Hyprland versions.

[fdev31]

To unset the windowrule I couldn't find it, so I only disable the workspace related properties for now... I could also force a "float off"... if someone is impacted and can provide some feedback about it please express your opinion!

[bmethod]

To unset the windowrule I couldn't find it, so I only disable the workspace related properties for now... I could also force a "float off"... if someone is impacted and can provide some feedback about it please express your opinion!

Yeah I'm impacted

On pyprland-git with 0.53.0, my zen browser scratchpads work but the float rules persist after hiding. Since my main browser also uses zen (same class), it opens floating even though it's not a scratchpad.

Current workaround is forcing tile in my keybinding:
bind = $mainMod_SHIFT, I, exec, $browser; sleep 0.5 && hyprctl dispatch settiled

If float off could be applied when hiding, that would solve it for me.

[fdev31]

I tried to mess with named window rules and think I found a way to create them using IPC so I can disable it easily.
@bmethod can you give it another shot, your workaround might not be needed anymore

[migueldamota]

@fdev31 Seems to be working just fine now 👍

[fdev31]

Just released 2.6.0 that should implement support for Hyprland 0.53.0.
Thank you for the collaborative work!