[HowTo] Easily customize GTK2 icon themes

Difficulty: ★★☆☆☆

Best suited for the odd icon change here or there, not for a whole whack of icons. There are better, more efficient ways for massively modifying themes which reading this will not assist with.


Like a theme but hate some of the icons? You can fix that real easily by exploiting theme inheritance and with a little bit of effort. Ahead will be some basics about how a theme index functions, how to adjust a theme using this index and additional information regarding display in appearance settings.

I use MATE desktop so my experiences are primarily for that. Though, this information should apply to any other GTK2 / GTK3 desktops such as XFCE, LXDE and the like.

For this example, we’ll change start-here.svg. Nothing about editing icons will be covered here as you should be familiar or willing to play with Inkscape for best effect.

Small-batch modding

Ideally, your changes reflect the directory structure of the original theme. To make this easier and less convoluted, change into where the themes are.

:heavy_dollar_sign: In xdg-terminal or preferred emulator:

cd $HOME/.icons

:fast_forward: For brevity, I’ll assume Numix as the focus icon theme, and that it had already been copied from /usr/share/icons. For any icon theme held in system root you should copy to $HOME/.icons. If this directory does not exist, make it. Later on if you want the theme to apply across the whole system it can be moved into /usr/share/icons so other account holders can apply it.

Further your copy will assume the name of MyNumix.


Copying directory structure
The importance of duplicating the directory structure is beyond my capacity to stress. To not do this is to quite possibly ensure complete failure of the task. Assuming the theme in question is Numix, this example command will do everything you need for duplicating the folder structure.

:heavy_dollar_sign: In xdg-terminal or preferred emulator:

mkdir $PWD/MyNumix
cd $PWD/MyNumix
rsync -a -f"+ */" -f"- *" /usr/share/icons/Numix $PWD
# Assuming you cd'd into .icons earlier...
Understand the rsync command

-a: [A]rchive mode; equals -rlptgoD

  • -r: [R]ecurse into directories
  • -l: [C]opy symlinks as symlinks
  • -p: [P]reserve permissions
  • -t: [P]reserve modification times
  • -g: [P]reserve group
  • -o: [P]reserve owner (super-user only)
  • -D: [S]ame as --devices --specials
    • --devices: This option causes rsync to transfer character and block device files to the remote system to recreate these devices. This option has no effect if the receiving rsync is not run as the super-user
    • --specials: This option causes rsync to transfer special files such as named sockets and fifos.

-f: [A]dd a file-filtering RULE (Two are used in the above command.)

Deleting unnecessary branches
This is best handled in your file explorer. In the original theme, find the icons you wish to replace. For this instance with Numix there are multiple icons sorted by size with the same file name, so to seek those out a full directory listing can be used with grep to find all instances of that icon. An example in the terminal for start-here.svg as shown below.

In xdg-terminal or preferred emulator

find /usr/share/icons/Numix | grep start-here.svg



As you can see, find here is going to be your best friend. For brevity sake start-here is the only icon this guide will be tampering with. find can also be used with other commands to automate mass deletion on a per-directory basis but due to how easily that can be botched this guide won’t bother covering the finer aspects of executing other commands with find — Just spend some time finding the directories you wish to keep and move along.

Making the change

Preparing assets
So now, the only locations in each icon size-sorted directory for this example using Numix in $HOME/.icons/MyNumix should be places. Find and modify to preference the icon you wish to use as start-here.svg, saving them in the appropriate locations.

Modifying index.theme

Due to the length of this file, only the line numbers of this file specifically for the Numix theme will be mentioned. While potentially harder to follow, it saves this post from having a massive wall of text. As this will vary between themes, best judgment should be exercised with other themes.

Before beginning, copy the index.

:heavy_dollar_sign: In xdg-terminal or preferred emulator:

cp /usr/share/icons/Numix/index.theme $PWD

Now, open the copy of index.theme held in $HOME/.icons/MyNumix. It looks a bit daunting, but breaking the file’s components down makes it way easier to understand. As follows:

2: Theme name. Change this to something you can identify in your appearance properties later.
4: Optional description.
6: Theme inheritance. Explained in-depth later.
8: Theme selection icon. Will accept any icon which exists in itself or heirs.
10: Theme directories. Treating these as classes will make the rest easier to understand.
12-∞: Theme directory properties. One definition per directory defined in line 10.

Understanding the individual components of the theme index, it would be best to modify this so only the directories which matter are included. So from line 10, delete everything which wasn’t kept in $HOME/.icons/MyNumix. As these directories won’t be in the list anymore, also delete any definitions past line 11 which were removed from line 10.

For the previous examples where the only icon of concern is start.here.svg, the places directory of each size should be the only locations listed in lines 10 and only definitions of those directories should be shown past line 11.

Line 6 demands considerate attention. The Inherits attribute will use existing themes by theme name in /usr/share/icons or $HOME/.icons. It will use the first theme listed, and if that doesn’t have a suitable icon, any directories subsequently after — similarly to the font-family selector in CSS.

This means, the name of the theme, not the name as shown in directory. If an Inherits declaration isn’t working, check your appearance settings or the heir theme’s index for correct name.

The following change must be made to use the remainder of the Numix icon theme.

:spiral_notepad: In $HOME/.icons/MyNumix for line 6:


Otherwise, when selected only the default GNOME theme and high colour icons will be used.

Line 8 can be left alone, but to make it stand out, this change should be made:

:spiral_notepad: In $HOME/.icons/MyNumix for line 8:


After giving it a different name and optional description, save it. Open your appearance properties dialogue and you should see your theme appear and if applicable, the example icon defined for it.