Two cursor files survived the move off Windows. The arrow worked on the first try β and then it started showing up on links, where the other cat was supposed to be.
The Situation
A pair of .cur files: the same cat drawn twice, mouth closed for the arrow, mouth open for anything that should react. On Windows that is a settings panel and ten seconds of clicking. Cursors are one of those things the OS hides completely, right up until you leave.
On Omarchy 4.0.6 with Hyprland 0.56.2 the file copy took ten seconds too. Getting them to draw took four acts, and only one of them was about the files.
Act I: .cur Is a Windows Container
A .cur is not an image. It is an ICO-family container: one or more bitmap sizes, a hotspot baked into the header, and no opinion about which filesystem it sits on.
Wayland has no reader for that container. Hyprland reads hyprcursor themes instead: a directory with a manifest, one subdirectory per cursor shape, and PNG frames at every size you want to support. Installed themes get packed down to .hlc blobs.
The conversion path that avoids every Windows-only tool is Pillow, which reads .cur directly:
from PIL import Image
im = Image.open("cursor.cur").convert("RGBA") # 32x32 RGBA, single frame
im.save("image32.png")
im.resize((64, 64), Image.NEAREST).save("image64.png")
Layout for a theme called mouclose:
mouclose/
βββ manifest.hl
βββ hyprcursors/
βββ left_ptr/{image32.png,image64.png,meta.hl}
βββ pointer/...
βββ text/...
manifest.hl names the theme and points at the shape directory. Each meta.hl declares which cursor names that shape answers to:
resize_algorithm = nearest
hotspot_x = 0.0
hotspot_y = 0.0
define_override = left_ptr
define_override = arrow
define_override = default
define_size = 32, image32.png
define_size = 64, image64.png
Those names are the same ones X11 has used for decades: left_ptr for the arrow, pointer for the hand over a link, text for the I-beam in a field, wait and progress for busy, grab for dragging. That mapping is the entire trick. The desktop does not know your cat exists; it asks for βpointerβ and takes whatever answers.
Compile and install:
hyprcursor-util --create ./mouclose # writes ./theme_mouclose
cp -r theme_mouclose ~/.local/share/icons/mouclose
hyprctl setcursor mouclose 32
Three shapes, and the tool is explicit about it: Done, written 3 shapes.
Act II: hl.env Is a Function, Not a Table
Omarchy 4 moved its Hyprland config to Lua. Files live in ~/.config/hypr/*.lua β looknfeel.lua, monitors.lua, bindings.lua β and they load after the distro defaults in /usr/share/omarchy/default/hypr/.
We wrote the obvious thing:
hl.env.set("HYPRCURSOR_THEME", "mouclose")
hl.env.set("HYPRCURSOR_SIZE", "32")
Hyprland answered with the red config-error overlay:
Your config has errors:
attempt to index a function value (field 'env')
~/.config/hypr/looknfeel.lua:53
hl.env is a function. The correct call is positional:
hl.env("HYPRCURSOR_THEME", "mouclose")
hl.env("HYPRCURSOR_SIZE", "32")
The reference was already on disk. /usr/share/omarchy/default/hypr/envs.lua sets the whole session environment in about forty lines, and every one of them looks like hl.env("XCURSOR_SIZE", "24"). Reading the defaults file that your config is layered on top of would have skipped this act entirely.
Ordering matters as well. The defaults set HYPRCURSOR_SIZE to 24; looknfeel.lua loads after them, so the later assignment wins and the cursor gets its 32 pixels.
Act III: The Arrow Had Already Claimed the Link Shape
The cursor drew. Links still showed the closed mouth.
The source meta.hl for left_ptr listed four overrides, and one of them was pointer. The arrow shape was answering the link handβs name, so there was no gap for the open-mouth art to fill, no matter how many images we compiled into it.
The fix is one deleted line and two new shape directories:
resize_algorithm = nearest
hotspot_x = 0.0
hotspot_y = 0.0
define_override = pointer
define_override = hand1
define_override = hand2
define_size = 32, image32.png
define_size = 64, image64.png
Same again for text, with text, xterm and ibeam as aliases. Recompile, hyprctl setcursor, and the meow cat appears over links and text fields while the quiet cat stays on the arrow.
Act IV: βokβ Proves Nothing
hyprctl setcursor answers ok. It also answers ok for a theme that does not exist:
$ hyprctl setcursor definitely_not_a_theme_xyz 32
ok
The Hyprland log has nothing to say about either call, so the log is not a witness. Screenshots are not a witness either. grim -c asks the compositor for a frame, but the pointer is drawn on a hardware plane, so scanning a 32x32 window at the pointerβs coordinates found no coloured pixels at all. The X11 desktop-capture path fails outright with a GetImage error.
What does prove it: .hlc files are containers with the PNGs still inside. Scan for the PNG signature, extract, hash:
left_ptr.hlc -> 06b7a0f416 (closed mouth)
pointer.hlc -> 596fe2e48f (open mouth)
text.hlc -> 596fe2e48f (open mouth)
Both hashes match the source art exactly, which is a stronger statement than any CLIβs ok. The last check is human: someone has to move the mouse and look. That is the only test a fallback theme cannot fake.
Receipts
$ pacman -Q hyprcursor
hyprcursor 0.1.13-7
$ hyprctl version | head -1
Hyprland 0.56.2 built from branch v0.56.2 at commit efb5099...
$ cat ~/.local/share/icons/mouclose/manifest.hl
name = mouclose
description = Windows cat cursors: closed mouth (arrow), open mouth (links + text). 32px, hotspot top-left.
version = 0.1
cursors_directory = hyprcursors
$ ls ~/.local/share/icons/mouclose/hyprcursors/
left_ptr.hlc pointer.hlc text.hlc
$ hyprctl configerrors
$
That empty last response is the whole point of the exercise.
Takeaway
A Windows cursor is three conversions away from a Wayland desktop: container to PNG, PNG to a named shape, shapes to a compiled theme. The names are the step people skip β left_ptr, pointer, text β and they decide whether the right art appears on the right widget.
When a tool reports success, find out whether it is capable of reporting failure. hyprctl setcursor is not, so verification has to happen somewhere else: inside the compiled artifact, or in a personβs eyes.
What to run
python3 -c "from PIL import Image; im=Image.open('cursor.cur').convert('RGBA'); im.save('image32.png'); im.resize((64,64), Image.NEAREST).save('image64.png')"
hyprcursor-util --create ./mytheme
cp -r theme_mytheme ~/.local/share/icons/mytheme
hyprctl setcursor mytheme 32
And in ~/.config/hypr/looknfeel.lua:
hl.env("HYPRCURSOR_THEME", "mytheme")
hl.env("HYPRCURSOR_SIZE", "32")