Catppuccin cursors: pastel mouse pointers for Linux desktops

What the project contains and where it came from

Catppuccin cursors is a set of soothing pastel mouse pointer themes for GTK, Plasma and Hyprland. The artwork is a modification of Volantes Cursors, and the README credits that project and the two people behind it, varlesh and elkrien.

The structure is the standard Catppuccin one. There are four flavours, Latte, Frappé, Macchiato and Mocha, each with a preview image in the assets directory, and within each flavour there is a set of accents. The justfile in the repository lists the sixteen accent names in full: blue, dark, flamingo, green, lavender, light, maroon, mauve, peach, pink, red, rosewater, sapphire, sky, teal and yellow. That count includes the neutral ones, so a flavour and accent combination is a specific named artefact rather than a hue you pick in a settings panel.

The four flavours and sixteen accents are the product, and the rest of the repository is the machinery that produces them.

The repository layout shows the shape of the pipeline. There is a src/ directory holding the source definitions, a build script, a scripts/ directory with a create_zips helper, a justfile driving the commands, and a flake.nix with flake.lock plus a default.nix and shell.nix for the Nix side. There is also a.release-please-manifest.json and a release-please-config.json, which is how the releases and the changelog are produced, and an AUTHORS file.

The primary language of the repository is Python, which is what the generation scripts use, and the licence is GPL-2.0 with the file at the root.

Installing a prebuilt theme from a release

The simplest path is the GitHub release. The README's instruction is to download your preferred flavour and accent from the latest GitHub release, and the release is versioned, v2.0.0 being the current one.

Then you extract the zip to one of two locations. For the local user that is $HOME/.icons, and for all users it is /usr/share/icons.

The example installation shows the sequence, downloading the Frappé flavour with the blue accent.

cd $HOME/.icons # or `/usr/share/icons`
curl -LOsS https://github.com/catppuccin/cursors/releases/download/v2.0.0/catppuccin-frappe-blue-cursors.zip
unzip catppuccin-frappe-blue-cursors.zip

After that you choose the theme in your settings, which on GNOME and Plasma means the pointer or mouse cursor panel and on Hyprland it is set through the desktop's cursor configuration.

The file name encodes both choices, catppuccin-frappe-blue-cursors.zip, so the artefact you want is determined by two variables before you download anything. There are no separate accent downloads to combine later, which is a small convenience, and it also means a user who changes their mind about the accent unzips a different file rather than editing anything.

The $HOME/.icons location is worth choosing over the system-wide one for a theme switch, since the user directory needs no root and can be replaced without touching the system.

Arch and NixOS packages

On Arch Linux, individual flavour packages are available through an AUR helper, one per flavour.

yay -S catppuccin-cursors-latte
yay -S catppuccin-cursors-frappe
yay -S catppuccin-cursors-macchiato
yay -S catppuccin-cursors-mocha

There is also a git package that builds the cursors from source, and this one contains all variants of flavour and accent rather than a single combination.

yay -S catppuccin-cursors-git

That distinction matters for a declarative setup. A flavour package gives you a fixed set of accents for that flavour, while the git package is the one to use if you want the full matrix available locally, at the cost of building it.

NixOS is handled through nixpkgs, where the package is called catppuccin-cursors. The README says to use it by providing your preferred flavour and accent in camelCase.

pkgs.catppuccin-cursors.mochaMauve

So the attribute name is the flavour followed by the accent, capitalised. That is the idiomatic Nix way of exposing a matrix of variants, and it means a NixOS user selects one combination in their configuration file and rebuilds, rather than downloading a zip.

The repository also has its own flake.nix, default.nix and shell.nix, so the development environment for building the cursors is itself declarative.

Building from source with just and whiskers

The manual route needs a specific toolchain, and the README lists it plainly. Python 3 to run the scripts in the codebase, whiskers to generate the cursor SVGs, xcursorgen to generate the cursors, and Inkscape to convert SVGs to PNGs. Just is listed as optional, to easily run development commands.

That list tells you the pipeline: whiskers turns the source definitions into SVG images, Inkscape renders those to PNG at the sizes a cursor theme needs, and xcursorgen packages the PNGs into the Xcursor format that the desktop actually loads.

The steps are a clone and a set of just commands.

git clone https://github.com/catppuccin/cursors.git
cd cursors

The justfile is short enough to read in full, and it is the clearest description of the build. There is a clean target that removes all files in the pngs, hl, dist, releases and svgs directories. There is a zip target that runs the create_zips script over the dist directory. And there are the build targets.

just all # Build all flavor-accent variants.
just build mocha # To build all variants under one single flavor.
just build mocha blue # To build only the blue variant under mocha.
just build mocha 'blue mauve peach' # To build only the blue, mauve, and peach variants under mocha.

The build command takes a flavour and an optional list of accents, and the justfile defines the accent list as a default argument, so calling build with only a flavour means all sixteen accents. The all target cleans first and then builds the four flavours in order, latte, frappe, macchiato and mocha.

When you are not sure what a command does, the README points at the justfile itself. The outputs land in the dist directory, and you extract them to $HOME/.icons or /usr/share/icons from there.

Where Catppuccin cursors is the wrong choice

The first limitation is the platform. The whole build chain depends on xcursorgen and on the Xcursor format, and the target desktops named in the project description are GTK, Plasma and Hyprland, all of which are Linux. A macOS or Windows user is out of luck, and there is no cursor format conversion in the repository.

The second is the manual build's weight. Four tools, two of which are graphics programs, for what is ultimately a set of pointer images. Whiskers, Inkscape and xcursorgen each have to be installed and working before the build produces anything, and the Inkscape step in particular is a full vector editor. That is a fair trade for a contributor and a heavy one for a user who just wants a different accent, which is why the release zips exist.

The third is the GPL-2.0 licence, which is a change of direction worth noting for anyone who has used the rest of the Catppuccin project. Anyone redistributing a modified version has to respect the copyleft terms, and a commercial product embedding these cursors has to think about that.

The fourth is the granularity of the choice. The accent is baked into the artefact name and into the file, and the README gives no way to recolour an accent after installation. If you want the rosewater accent in one application and teal in another, that is not a setting, it is two installations in two directories, and the desktop theme picker treats the pointer theme as a whole rather than per application.

The fifth is the release cadence relative to the rest of Catppuccin. The last push was on 2026-06-20 and the most recent release is v2.0.0 from February 2025, so the release artefact is over a year old while the repository has moved since. A theme that is only updated when the palette changes is not a problem, but it does mean the release zip and the current source are not necessarily identical.

Licence, maintenance and the cost of a cursor theme

The project is under the GPL-2.0 licence, with the LICENSE file at the root, and the footer carries the Catppuccin Org copyright from 2021 to the present.

The repository is not archived and the last push was on 2026-06-20, so the sources are still being worked on even though the release tags are older, with v2.0.0 from February 2025, v1.0.2 from December 2024 and v1.0.1 from October 2024. The version numbers track the format change, with the 1.x line being the first stable releases and 2.0.0 a repackaging.

Release automation is in place, with release-please managing the manifest, the config and the changelog, and there is a renovate.json for dependency updates and a CHANGELOG.md at the root.

The cost of a cursor theme is close to zero for a user, which is unusual for a piece of desktop theming and worth stating. You download a zip or add a package, and you have pointer images that load from the icon theme path. There is no daemon, no configuration file to maintain and no update mechanism beyond reinstalling a new zip.

The cost for a contributor is the opposite, since a new accent means regenerating the SVGs, rendering them and repackaging, and the accent list in the justfile is the place where that matrix is defined. The default.nix and shell.nix exist so that a contributor gets the same tool versions as the rest of the project, which is the practical answer to a build that depends on a graphics editor.

Editorial conclusion

Catppuccin cursors suits a Linux desktop user who wants a pointer set that matches a Catppuccin themed environment, with a prebuilt zip for the common case and a source build when you want a specific flavour and accent combination. It does not suit a macOS or Windows user, since the pipeline is built on xcursorgen and Inkscape. Verify the release artefact name before downloading, since the flavour and accent are both encoded in the file name, and pick the accent you want deliberately rather than installing every variant.

Frequently asked questions

Official sources

1. catppuccin/cursors on GitHub
2. Issues
3. License: GPL-2.0
4. README
5. Releases