# hyprcursor: a cursor format for Wayland that scales and stays small

> hyprcursor defines a cursor theme format with SVG support, configurable per cursor scaling and a far smaller on disk footprint than XCursor, and it ships the format spec, a C and C++ library for compositors and applications, and a utility for building themes. It is BSD-3-Clause licensed and lives in the Hyprland ecosystem.

**hyprwm/hyprcursor** — The hyprland cursor format, library and utilities.

- Repository: https://github.com/hyprwm/hyprcursor
- Website: https://standards.hyprland.org/hyprcursor/
- Stars: 580 · Forks: 31
- Language: C++
- License: BSD-3-Clause
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/hyprwm-hyprcursor

## What problem hyprcursor was built to solve

hyprcursor is the Hyprland cursor format, library and utilities. The reason it exists is stated bluntly in the documentation: XCursor sucks, and we still use it today, followed by three specific complaints. Scaling of XCursors is horrible. XCursor does not support vector cursors. XCursor is ridiculously space-inefficient.

Those three complaints are the design brief, and each one maps to a capability.

Automatic scaling according to a configurable, per-cursor method addresses the first. Instead of the client picking a bitmap size that happens to be close to the display scale, the theme declares how each cursor should scale, so the rendering side can produce a cursor that matches the actual output scale rather than nearest neighbour upscaling.

Support for SVG cursors addresses the second. A vector cursor stays sharp at any scale factor, which is the whole point of a HiDPI display, and the format makes that the normal case rather than an exception.

The third complaint is answered with a number the documentation gives. Way more space-efficient, as an example, Bibata-XCursor is 44.1MB, while it is 6.6MB in hyprcursor. That is a large part of a cursor theme, and cursor themes get shipped, cached and installed, so the size is a real cost.

The users are Wayland desktop users who care about cursor rendering on scaled displays, theme authors who want to publish in a modern format, and developers of compositors or applications that need to load cursor themes.

## Three pieces: the format, the library and the utility

The repository is split into three things, and they are useful to different people.

hyprcursor-util is the utility for creating hyprcursor themes, and it has its own readme in the hyprcursor-util/ directory. This is the piece a theme author uses.

libhyprcursor is the library to use for implementing hyprcursors in your compositor or app, and it provides C and C++ bindings. This is the piece a toolkit or compositor author uses, and it is the reason the project ships a library rather than only a file format.

The format specification itself lives outside the repository, on the Hyprland standards site, with a documentation wiki and a docs/ directory in the tree for the details that stay with the code.

The tree shows how it is laid out. There is a top level CMakeLists.txt, an include/ directory for the public headers, a libhyprcursor/ directory for the implementation, hyprcursor-util/ for the command line tool, tests/ with examples for both C and C++, and a hyprcursor.pc.in file, which is the pkg-config template used when installing the library so that other projects can find it with pkg-config. There is a nix/ directory with flake.nix and flake.lock, and a VERSION file.

The C and C++ bindings matter more than they might sound. Cursors are drawn by the graphics stack, which in the Wayland world is usually a toolkit with a C API, so a C binding is a practical requirement rather than a nicety, and the tests directory containing examples for both languages is the documentation of how to use it.

## Building the library and its dependencies

The build is CMake, and the dependency list is short enough to read at a glance. The requirements are hyprlang at 0.4.2 or newer, cairo for the rendering, libzip because a hyprcursor theme is an archive, librsvg for the SVG rasterisation, and tomlplusplus for the theme's TOML metadata.

The configure and build commands are:

```sh
cmake --no-warn-unused-cli -DCMAKE_BUILD_TYPE:STRING=Release -DCMAKE_INSTALL_PREFIX:PATH=/usr -S . -B ./build
cmake --build ./build --config Release --target all -j`nproc 2>/dev/null || getconf _NPROCESSORS_CONF`
```

The first line sets the build type and the install prefix, and the second builds every target. The parallelism expression is worth reading, because it is the portable form of nproc: it tries nproc first and falls back to getconf _NPROCESSORS_CONF when nproc is not there, which is the case on some systems.

Installing then uses:

```sh
sudo cmake --install build
```

The CMAKE_INSTALL_PREFIX of /usr in the configure line is what makes that install command put the library, the utility and the pkg-config file in the system locations, and the hyprcursor.pc.in template is instantiated from it.

The presence of the Nix flake means there is also a reproducible build path that does not depend on the distribution's packages, and the .clang-format and .clang-tidy files in the tree show that the project enforces a consistent C++ style and static analysis.

## What the documentation does and does not tell you

The README is a short pointer, and it points in three directions. There is a wiki entry, there is a docs/ directory in the repository, and there is the standards site for the format itself.

That is a reasonable structure for a specification project, where the authoritative text needs to live somewhere stable and versioned, but it does mean the README tells you very little about the format's actual contents. It does not describe the file layout, the metadata keys, the scaling methods, or how the per-cursor configuration is expressed. If you want to write a loader or a theme, you need the standards page and the wiki, and the README is only the signpost.

The same is true of the operational side. There is no configuration reference here, no list of supported scaling methods, and no compatibility table saying which applications can read a hyprcursor theme. The absence of a compatibility statement is the significant gap, because the format's whole advantage over XCursor is only realised if the software drawing your cursor understands it.

What the repository does say about the tools is precise. The library is the piece to use for implementing hyprcursors in your compositor or app, and the utility is for creating themes. That division is the one piece of guidance you need to pick your entry point, and it is enough to get started.

## Where hyprcursor is the wrong choice

The first limit is X11. hyprcursor is the Hyprland cursor format, and it exists to replace XCursor inside the Wayland world. A theme converted to hyprcursor is not readable by an X11 toolkit, and the documentation does not describe a fallback path. If your desktop still runs X11, or you need one theme to serve both an X11 session and a Wayland session, this format is the wrong side of that split.

The second is the requirement to adopt the format for the whole ecosystem around it. A compositor needs libhyprcursor to load the theme. The applications that draw cursors need it too. That is a distribution problem before it is a technical one, and it is the reason formats like this usually take years rather than months to become the default.

The third is the 0.x version line. The recent releases are v0.1.11 on 2024-12-21, v0.1.12 on 2025-03-17 and v0.1.13 on 2025-07-31. The repository is not archived, and the last push was on 2026-08-11, so the code is being worked on, but the most recent tag is over a year old relative to today, which means the format may have moved since v0.1.13 even though the source tree has moved since then.

The fourth is the middle ground the project does not occupy. A theme author can publish SVG based themes for the web and for the desktop, and the XCursor route is still the one that every application understands. hyprcursor is not a drop-in replacement for an XCursor theme in a mixed environment, and the documentation does not claim it is.

Compare that with the XCursor path. The difference in approach is that an XCursor theme carries a set of pre-rendered bitmaps at a few sizes, which is why it scales badly and why the formats are large, while a hyprcursor theme carries vector sources and lets the consumer render at the scale it needs. The trade is real quality and size on one side, and ecosystem reach on the other.

## Licence, ecosystem and what to check before you convert a theme

hyprcursor is released under the BSD-3-Clause licence, with the text in the LICENSE file at the repository root. The BSD 3 clause terms are permissive, with the usual obligations to keep the copyright notice and the licence text with copies, and no copyleft requirement on code that links against the library. For a compositor or a toolkit that wants to ship the library, that is the easy case, and you should read the LICENSE file yourself for the exact wording.

The project sits inside the Hyprland ecosystem, and the repository naming and the standards site make that clear, with the home page hosted at standards.hyprland.org/hyprcursor/ and the wiki at the Hyprland wiki under the Hypr Ecosystem section. The C++ and C nature of the code, with cairo, librsvg and hyprlang as dependencies, also places it squarely in the compositor stack rather than in application level tooling.

What to check before you convert a theme is a short list. First, read the standards page and the wiki, because the README does not contain the format details and the format is the product. Second, confirm that the applications you care about can load a hyprcursor theme at all, since a theme is only as good as the software reading it. Third, look at hyprcursor-util and work out whether your existing theme sources can be converted by it, or whether you need to author in the format directly, because the utility is a converter and a builder and what it accepts is a practical constraint on your workflow.

And keep the XCursor version of your theme until you have confirmed the new one works in your compositor and in the applications you use, because the format does not replace the old one in place, it sits alongside it.

## Conclusion

hyprcursor fits a Wayland desktop user or a theme author who wants crisp cursors at every scale factor and is willing to move away from the XCursor format, and the library is the right entry point for anyone writing a compositor or tool that has to load a cursor theme. It does not fit an X11-only setup, since the format is a Wayland answer to a Wayland problem, and it does not fit a project that needs the XCursor compatibility path. Before adopting it, read the standards page for the format and the wiki for the theme authoring rules, check that the utilities you need are in hyprcursor-util rather than only the library, and confirm your own compositor or application actually loads the hyprcursor format before converting a theme you rely on.

## FAQ

### What is hyprcursor and why does it exist?

hyprcursor is the Hyprland cursor format, library and utilities. It exists because the documentation lists three complaints about XCursor, namely horrible scaling, no support for vector cursors, and being ridiculously space-inefficient, and hyprcursor addresses all three.

### How much smaller is a hyprcursor theme than an XCursor theme?

The documentation gives one example: Bibata-XCursor is 44.1MB, while it is 6.6MB in hyprcursor. It attributes the difference to the format being far more space-efficient, with SVG support and automatic scaling.

### What are the build dependencies for hyprcursor?

The listed dependencies are hyprlang >= 0.4.2, cairo, libzip, librsvg and tomlplusplus. The build uses CMake, with a configure step that sets the build type and install prefix and a build step that compiles all targets in parallel.

### What are hyprcursor-util and libhyprcursor for?

hyprcursor-util is the utility for creating hyprcursor themes and has its own readme in the hyprcursor-util/ directory. libhyprcursor is the library for implementing hyprcursors in a compositor or app, and it provides C and C++ bindings, with examples for both in the tests/ directory.

### What licence does hyprcursor use?

hyprcursor is released under the BSD-3-Clause licence, with the terms in the LICENSE file at the repository root. The repository is not archived, the last push was on 2026-08-11, and the most recent release tag is v0.1.13 from 2025-07-31.

## Sources

- [hyprwm/hyprcursor on GitHub](https://github.com/hyprwm/hyprcursor)
- [License: BSD-3-Clause](https://github.com/hyprwm/hyprcursor/blob/main/LICENSE)
- [Project website](https://standards.hyprland.org/hyprcursor/)
- [README](https://github.com/hyprwm/hyprcursor/blob/main/README.md)
- [Releases](https://github.com/hyprwm/hyprcursor/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/hyprwm-hyprcursor