Where Icon Themes Live on Linux: /usr/share/icons, ~/.icons and index.theme Decoded

Unpacking an icon theme to the right Linux directory and keeping your index.theme organized are key steps to making a newly-added icon theme visible to your desktop. With multiple base directories to place themes, and a proper index.theme file required by most desktop environments, the index.theme file required by most desktop environments, various elements must be present for the theme to appear. Starting with the default theme base directories to the responsive keys in a wellformed index.theme, this guide will take you through what it takes for your icon themes to be usable.

Where the Desktop Looks First

When hunting for themes, the desktop does not check every icon directory on the system. The default base directories in priority order are:

1. $HOME/.icons (this is the user's default themes base)
2. /usr/share/icons (this is the all-user default, empty by default)
3. /usr/share/pixmaps (another standard icon folders)

Any index.theme in these folders or subdirectories is scanned. The icon search path is the final arbiter of what icons gets scanned. The only thing that matters is how the index sees the new theme.

The search always begins with the current theme, then checks the Inherits property to recursively parse through each parent theme, and terminates on the default hicolor theme.

What index.theme Is

index.theme is the INI-style configuration file at the root icon folder that describes \ the theme and its subdirectories. The most important section in the file is `` which describes the theme name, etc.

The file lists the subdirectories of the icon theme in the Directories= key, and checks for each directory with its own section. For example:

 
 Context=Actions
 Size
 Type=Threshold

How Directories= and Per-Folder Sections Work

Within the index.theme file, the Directories= key lists the subdirectories of \ each theme. Those subdirectories must correspond to a section in the index.theme \ file, describing that directory. For example, given this Directories line:

 Directories=cursors/status;devices/scalable;places/scalable;actions/scalable;

The file must also include a ` section, a ` \ section, etc.

The subdirectory name in Directories= must exactly match the later section \ header. For example:

 Directories=status/scalable
 
 Context=Status
 Size=16
 MinSize=16
 MaxSize=1024
 Type=Scalable

Reading the Per-Directory Keys

Each per-directory section in an index.theme file assigns metadata to that \ subdirectory's icons, such as the contextual size, minimum and maximum size, \ and any other descriptor. Some of the practical keys in a typical `` section include:

Context: the type of icon, such as actions or places Size: the nominal icon size, such as 16 MinSize / MaxSize: the size range the icons in this directory can be used scaled Scale: specifies settings like HDPI icons Type: icon usage type, such as Threshold

These practical keys are needed to give the desktop meaningful context about \ the icon directory, such as which icon sizes are valid, or what the folder \ content is for, such as "places" or "actions" icons.

Why the Theme Still May Not Show Up

Even with a valid theme directory and a proper index.theme file \ in one of the base searched icon folders, the icon theme won't show up \ until the cache is built with gtk-update-icon-cache, which expects \ a top level theme directory with index.theme at the root.

The command requires valid theme directories, and will exit with an \ error for unexpected top level contents, so ensure you are running \ the following in the root of your unpacked theme folder:

 $ gtk-update-icon-cache ~/.icons

Without `--ignore-theme-index`, `gtk-update-icon-cache` requires the \
theme directory to contain `index.theme` at the root.

What Belongs in the Fallback Chain

In the theme lookup, both the fallback chain and the cached directory \ references the Inherits= property in index.theme to see which parent \ themes should be explored next. During the recursive descent, hicolor is \ always last, as it is the final catch-all default.

The final way a theme will show up is having its icons satify the \ specification of its parent themes, down the chain until hicolor.

Conclusion

In summary, index.theme names the directories, the icon lookup trivially falls to hicolor, and the cache must be regenerated after arriving at \ the terminal fallback for the desktop to render the final icon.