Cursor themes

From ArchWiki
(Redirected from Mouse Cursors)

The display server is accompanied by a cursor theme that helps various aspects of GUI navigation and manipulation. The display server includes a cursor theme, however, other cursor themes can be installed and selected.

Installation

Installation can be done with a package, or downloaded and extracted to an appropriate directory.

Packages

Cursors themes are available in the:

Manually

If a cursor theme is not available in the official repositories or the AUR, it can be added manually. A number of websites exist where cursor themes can be downloaded. Once downloaded, they need to be put in the icons directory (as cursors have the ability to be bundled with icon themes).

Some websites that have cursor themes:

For user-specific installation, use the ~/.local/share/icons/ or ~/.icons/ directory. Extract them with this command that will work for most archives:

$ tar xvf foobar-cursor-theme.tar.gz -C ~/.local/share/icons

The cursor theme directory structure is theme-name/cursors, for example: ~/.local/share/icons/theme/cursors/; make sure the extracted files follow this structure.

Note: For system-wide installation the /usr/share/icons directory is used. Direct extraction to this directory is usually discouraged as files here are not tracked by pacman; it is recommended to create a package for the cursor theme instead.

Already installed cursor themes can be viewed with the command:

find /usr/share/icons ~/.local/share/icons ~/.icons -type d -name "cursors"

If the package includes an index.theme file, check if there is an "Inherits" line inside. If yes, check whether the inherited theme also exists on the system (rename if needed).

Configuration

There are various ways to set the cursor theme. The cursor's appearance may change from one window to another if programs are reading different configurations. The inconsistency is most common between GTK programs and Qt programs, so it's important to know where our configurations are coming from.

XDG specification

This method applies to both X11 and Wayland cursor themes.

For user-specific configuration, create or edit either:

  • ~/.icons/default/index.theme
  • ~/.local/share/icons/default/index.theme

For system-wide configuration, one can edit:

  • /usr/share/icons/default/index.theme

The Inherits option in the [icon theme] section must be set to the xcursor theme directory name cursor_theme_name, for example Breeze_Snow:

~/.icons/default/index.theme
[Icon Theme] 
Inherits=cursor_theme_name

If it still does not work, try creating a symlink from ~/.icons/default/cursors (assuming user-specific) to .local/share/icons/cursor_theme_name/cursors.

Restart X for any of the changes to take effect.

GTK and Qt configuration files

GTK

In addition to a properly configured ~/.icons/, there is a cursor option in GTK's config, but it's rare that programs need it.

~/.gtkrc-2.0
gtk-cursor-theme-name="cursor_theme_name"
~/.config/gtk-3.0/settings.ini
[Settings]
gtk-cursor-theme-name=cursor_theme_name

Qt

Qt configuration does not specify the cursor, Qt programs simply use the cursor in ~/.icons/ (as specified in the #XDG specification). To make Qt programs also use ~/.local/share/icons/ the XCURSOR_PATH enviroment variable must be set.

LXAppearance

LXAppearance sets the default cursor by creating an ~/.icons/default/index.theme file: if you edited that file manually, LXAppearance will overwrite it.

Desktop environments

Desktop environments use the XSETTINGS protocol, typically implemented through a settings daemon. While this allows to change the cursor on-the-fly, the applied theme may be inconsistent across applications. See #XDG specification to change the cursor theme manually.

GNOME

To change the theme in GNOME, use gnome-tweaks or set the configuration directly with:

$ gsettings set org.gnome.desktop.interface cursor-theme cursor_theme_name

Change the cursor size with (depending on the theme, sizes are 24, 32, 48, 64):

$ gsettings set org.gnome.desktop.interface cursor-size cursor_theme_size
Note: By default, on Wayland, Gnome applications should be unable to display your cursor themes located in ~/.local/share/icons. As a workaround, you can add that path to XCURSOR_PATH.

KDE (Wayland)

xdg-desktop-portal-gtk must be installed for GTK/Gnome applications to correctly apply cursor themeing on Wayland.

MATE

In MATE one can use mate-control-center or gsettings. To change the theme:

gsettings set org.mate.peripherals-mouse cursor-theme cursor_theme_name

To change the size:

gsettings set org.mate.peripherals-mouse theme-size

XFCE

To change the xcursor theme, use:

xfconf-query --channel xsettings --property /Gtk/CursorThemeName --set cursor_theme_name

To change the size:

xfconf-query --channel xsettings --property /Gtk/CursorThemeSize --set cursor_theme_size

X resources

To locally name a cursor theme, add to the ~/.Xresources file:

Xcursor.theme: cursor-theme

To have the cursor theme properly loaded, it will need to be done so by the window manager; if it does not, it can be forced to load prior the window manager by putting the following command in ~/.xinitrc or .xprofile (depending on ones personal setup):

$ xrdb ~/.Xresources

Optionally, add this line to ~/.Xresources if your cursor theme supports multiple sizes:

Xcursor.size: 16
Tip: 32, 48 or 64 may also be good size.

If in doubt over supported cursor sizes, start X without this setting and let it choose the cursor size automatically. (Refer to your window manager documentation for details.)

Environment variable

You can use an environment variable to set a theme for a single application to try it out temporarily, for example:

$ XCURSOR_THEME=SomeThemeName xclock

XCURSOR_SIZE is optional if your cursor theme supports multiple sizes.

If cursor themes are installed in ~/.local/share/icons, in order to avoid possible issues, add that path to XCURSOR_PATH. For example:

~/.bash_profile
export XCURSOR_PATH=${XCURSOR_PATH}:~/.local/share/icons

Display managers

Cursor theme can usually be set within a display manager, but keep in mind the cursor theme may not carry over to the user session.

GDM

See GDM#Changing the cursor theme.

Tor Browser

Tor Browser has its own "virtual" home directory and does not read the file in the user's home directory. Therefore you need to copy configuration and icon themes to the Tor Browser installation directory.

This article or section needs language, wiki syntax or style improvements. See Help:Style for reference.

Reason: We do not need a script to instruct the user to copy several files. (Discuss in Talk:Cursor themes)
# $HOME of tor browser
TBHOME=~/.local/share/torbrowser/tbb/x86_64/tor-browser/Browser
# path to tor browser's gtk3 settings.ini
TBG3RC=$TBHOME/.config/gtk-3.0/settings.ini
# your user's directory where custom cursors are stored, might be below .local/share/ instead
ICONSDIR=~/.icons

# make sure first line of the settings.ini is '[Settings]'
[ -f $TBG3RC ] && [ $(head -1 $TBG3RC) == '[Settings]' ] || echo '[Settings]' >> $TBG3RC
# add your gtk3 settings to torbrowser's, strip leading [Settings] tag line
tail -n +2 ~/.config/gtk-3.0/settings.ini >> $TBG3RC
# copy your cursor files to torbrowser
# ONLY NEEDED IF YOU HAVE CURSORS NOT INSTALLED SYSTEM-WIDE
cp --recursive $ICONSDIR $TBHOME/

Troubleshooting

Create links to missing cursors

Applications may keep using the default cursors when a theme lacks some cursors. This can be corrected by adding links to the missing cursors. For example:

$ cd ~/.icons/theme/cursors/
$ ln -s right_ptr arrow
$ ln -s cross crosshair
$ ln -s right_ptr draft_large
$ ln -s right_ptr draft_small
$ ln -s cross plus
$ ln -s left_ptr top_left_arrow
$ ln -s cross tcross
$ ln -s hand hand1
$ ln -s hand hand2
$ ln -s left_side left_tee
$ ln -s left_ptr ul_angle
$ ln -s left_ptr ur_angle
$ ln -s left_ptr_watch 08e8e1c95fe2fc01f976f1e063a24ccd

If the above does not solve the problem, look in /usr/share/icons/whiteglass/cursors for additional cursors your theme may be missing, and create links for these as well.

Tip: You can also remove unwanted cursors. To for example remove the "watch" cursor:
$ cd ~/.icons/theme/cursors/
$ rm watch left_ptr_watch
$ ln -s left_ptr watch
$ ln -s left_ptr left_ptr_watch

Supplying missing cursors

Some programs set their own custom cursors ~/.Xresources which you may want to override. A common example of this is rdesktop, which connects to a Microsoft Windows computer and uses the cursors obtained from the remote machine, which can often be difficult to see due to protocol limitations yielding poor conversion quality.

This can be resolved by replacing these cursors with ones from the same (or another) cursor theme. In order to do this, the hash of the image must be obtained. This is done by setting the XCURSOR_DISCOVER environment variable prior to launching the application that sets these cursors:

$ XCURSOR_DISCOVER=1 rdesktop ...

The first time (and only the first time) the cursor is set, some details will be displayed, like this:

Cursor image name: 24020000002800000528000084810000
...
Cursor image name: 7bf1cc07d310bf080118007e08fc30ff
...
Cursor hash 24020000002800000528000084810000 returns 0x0

When Xcursor looks for missing cursors, the search path includes ~/.icons/default/cursors so this is where an image can be placed for Xcursor to find. First, create this directory if it does not already exist:

$ mkdir -p ~/.icons/default/cursors

Then link the hash to the target image. Here we are using the left_ptr image from the Vanilla-DMZ cursor theme:

$ ln -s /usr/share/icons/Vanilla-DMZ/cursors/left_ptr ~/.icons/default/cursors/24020000002800000528000084810000

The change will be visible as soon as the application is restarted. No special method of launching the application is required.

Change X shaped default cursor

The default X shaped Xcursor appears in window managers that do not set the default cursor to left_ptr or in window managers using XCB (like awesome) instead of Xlib.

To fix this, simply add the following to your ~/.xinitrc, xsession or window managers startup configuration if possible (for example bspwm's bspwmrc).

$ xsetroot -cursor_name left_ptr

The list of cursor styles is in appendix B of the X protocol.

.Xdefaults

If you have conflicting cursors then it might be because a different cursor has been set in the ~/.Xdefaults file.

Cursor size does not change on startup

If you are trying to change cursor size via ~/.Xresources in your ~/.xinitrc and it does not work, make sure that xrandr runs before loading ~/.Xresources.

Make sure your ~/.xinitrc looks similar to the following

~/.xinitrc
xrandr
...
xrdb -merge ~/.Xresources
exec wm

Cursor size or theme does not change on Plasma (Wayland)

When changing the cursor size or theme when using Plasma under Wayland, make sure to restart the session after applying the changes [1] [2].

This is a bug. See a workaround at KDE#Plasma cursor sometimes shown incorrectly.

See also

  • Xcursor(3) — For more information about cursors in X (supported directories, formats, compatibility, etc.).
  • For the creation of cursor files, see Xcursorgen