hyprcursor

hyprcursor is a new cursor theme format that has many advantages over the widely used XCursor.

Hyprcursor Themes

You will need to obtain those yourself. If you are on the Discord server, see #hyprcursor-themes.

Put your theme(s) in ~/.local/share/icons or ~/.icons

You can set your theme with envvars, or with hyprctl setcursor.

Env:

• HYPRCURSOR_THEME controls the theme.
• HYPRCURSOR_SIZE controls the cursor size.

Example snippet of hyprland.lua:

hl.env("HYPRCURSOR_THEME", "MyCursor")
hl.env("HYPRCURSOR_SIZE", "24")

Creating / Porting Themes

Go to the hyprcursor repo

See the docs/ and hyprcursor-util/ directories for instructions.

Important Notes

Although many apps support server-side cursors (e.g., Qt, Chromium, Electron, Hypr Ecosystem) some apps still don’t (e.g., GTK).

Apps that do not support server-side cursors and hyprcursor will still fall back to XCursor.

For those apps, you need to export XCURSOR_THEME and XCURSOR_SIZE to a valid XCursor theme, and run

gsettings set org.gnome.desktop.interface cursor-theme 'THEME_NAME'

for GTK.

If GSettings schemas are not available to you (e.g., on NixOS you will get No schemas installed), you can instead run:

dconf write /org/gnome/desktop/interface/cursor-theme "'THEME_NAME'"

If the app is a flatpak, run:

flatpak override --filesystem=~/.themes:ro --filesystem=~/.icons:ro --user

and put your themes in both /usr/share/themes and ~/.themes. Also put your icons and XCursors in both /usr/share/icons and ~/.icons.

I Don’t Want to Use hyprcursor

If you don’t have any hyprcursor themes installed, Hyprland will fall back to XCursor, and use whatever you define with XCURSOR_THEME and XCURSOR_SIZE.

My Cursor Is a Hyprland Icon?

See FAQ