ani2xcursor

Interactively convert Windows .ani animated cursors into a proper Linux XCursor theme.

ani2xcursor scans a folder for .ani files, guesses a sensible X11 cursor name for each one (which you can accept, change, or pick from a menu), asks what size you want the cursors rendered at, and builds a ready-to-use cursor theme complete with an index.theme and optional compatibility symlinks (default, pointer, xterm, …).

$ python3 ani2xcursor.py

============================================================
 .ani -> Linux XCursor  (interactive)
============================================================

Directory to scan for .ani files [.]:

Found 9 .ani file(s) in .:
  1. Classic cursor Brushbuddy.ani
  2. Diagonal resize1 Brushbuddy.ani
  ...

Which ones to convert? (comma-separated numbers, or 'all') [all]:

  Classic cursor Brushbuddy.ani  ->  cursor name [left_ptr] (or 'l' for list):
  ...

Choose the final cursor size
  1. 24x24 px
  2. 32x32 px (default)
  3. 48x48 px
  4. 64x64 px
  5. 96x96 px
  6. 128x128 px
  7. Custom size...
Choose the final cursor size [2]:

Theme name [MyCursors]:
Install cursors under which base directory? [/home/you/.local/share/icons]:

Features

• 🔍 Auto-discovery of .ani files in a directory, or add files manually by path
• 🧠 Smart name guessing from the filename (resize, move, link, wait, text, …), always overridable
• 📋 Standard cursor name picker — browse ~28 common X11 cursor names with descriptions
• 📏 Configurable output size (24–128px presets, or any custom size)
• 🎯 Correct hotspot scaling, computed from each cursor's actual native resolution (not assumed)
• 🎞️ Full animation support — multi-frame .ani files convert to animated XCursors with the original frame timing preserved
• 🔗 Optional alias symlinks (default, pointer, xterm, watch, …) for wider app compatibility
• ✅ Dependency checks with install hints if ImageMagick or xcursorgen are missing

Requirements

• Python 3.8+
• ImageMagick (provides the magick command)
• xcursorgen (from xorg-xcursorgen on Arch, x11-apps on Debian/Ubuntu)

Install on Arch Linux:

sudo pacman -S imagemagick xorg-xcursorgen

Install on Debian/Ubuntu:

sudo apt install imagemagick x11-apps

Usage

git clone https://github.com/AValzzzz/ani2xcursor.git
cd ani2xcursor
python3 ani2xcursor.py

Answer the prompts:

1. Which directory to scan (or add .ani files manually by path)
2. Which files to convert
3. What X11 cursor name each one maps to
4. The final pixel size
5. The theme name and install location

The theme is written to <base directory>/<theme name>/, following the standard XCursor layout:

~/.local/share/icons/MyCursors/
├── index.theme
└── cursors/
    ├── left_ptr
    ├── hand1
    ├── wait
    └── ...

Activating the theme

GNOME:

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

KDE Plasma / most other desktops: open System Settings → Appearance → Cursors and select the theme from the list.

You may need to log out and back in for every application to pick up the change.

How it works

.ani files are RIFF containers holding a sequence of standard Windows .cur frames plus timing metadata. The script:

1. Parses the anih header to get frame count and frame delay (jifRate, in 1/60s units → converted to milliseconds)
2. Walks the RIFF/LIST chunk tree to pull out each embedded icon (.cur) frame
3. Reads each frame's hotspot from the .cur header and rescales it to match the requested output size
4. Uses ImageMagick to render each frame to a PNG at the target size
5. Feeds the frames, hotspot, and delay into xcursorgen to produce a single XCursor binary per cursor name

Contributing

Issues and pull requests are welcome — in particular, more filename keyword patterns for the auto-guesser, and additions to the standard cursor name list.

License

MIT