I am trying to create one theme for GTK+ and while doing so, I found index.theme. Now, where do I find specification for this file similar to Icon Theme and Desktop entry?

  • 1
    I am not sure, if you read question or not, I have mention word theme and the link is for icon. If you read in first link you find that icon's index.theme must start with [Icon Theme]. I have not seen yet any theme's index.theme file which has this definition.
    – Kiran
    Commented Jan 5, 2017 at 6:48
  • Perhaps 'index.theme' is being used for backward compatibility, since it was last mentioned by GNOME 2 documentation and not much else based on my findings. More details in my delayed answer below.
    – user37165
    Commented Jan 10, 2017 at 17:53

3 Answers 3


There is nowhere to be found.

The 'index.theme' specification for GTK+ theme doesn't seem to be documented anymore since GNOME 2 had deprecated. Both GTK+ and GNOME Developer websites are essentially having zero documentation about 'index.theme' for GTK+ theme.

Known documentation

The earliest known documentation, GNOME 2.4 Desktop System Administration Guide, was last updated in 2003. That is possibly the original 'index.theme' specification for GTK+ theme.

[Desktop Entry]
Name=High Contrast Large
Name[es]=Alto contraste grande
Comment=Large black-on-white text and icons
Comment[es]=Textos e iconos grandes en negro sobre blanco

ApplicationFont=sans 18

Following that, some changes have been introduced in GNOME mailing list dated July 2004 and October 2004 (only latter is quoted below). Unfortunately, there is no updated documentation by GTK+ or GNOME developers to illustrate those changes.

gnome-theme-manager currently handles GTK, Metacity and Icon themes, but could be extended to handle splash screens and backgrounds (possible integration with current background chooser?).

A relatively new documentation, Gnome Theme Package format by Xfce, was last updated in 2010. This included more variables in the index.theme file that are not found in the original specification and reflects some of the changes mentioned in GNOME mailing list.

[Desktop Entry]
Name=example theme



Supporting fact has been found in Artwork/Documentation/GTK-Themes on Ubuntu Wiki, which mentioned one of the additional variables. This material however, was last updated in 2009.

In your index.theme file put a line like "BackgroundImage=/absolute/path/to/image.png" under the X-GNOME-Metatheme header. For packaged themes wallpapers should be assumed to be placed in /usr/share/wallpapers.

To use or not

If you are less confident to use the provided example in outdated documentation, I'd suggest to copy index.theme file from existing THEME and modify accordingly. GTK+ themes will include the file at /usr/share/themes/THEME/index.theme in some Ubuntu and official flavours.

Another way to use index.theme file is, by not having to write one.

There is at least one example that demonstrates custom GTK+ theme could just reference to existing file by using symbolic link. This way, it is possible to create slightly modified version of existing theme in less time and without having to worry about the specification of index.theme file.

TL;DR The most recent documentation that you can find today, albeit without explanation, is Gnome Theme Package format by Xfce. Or just forget that and follow what other themes do.

  • 1
    Personally, I like the idea of hacking an existing example. ;-)
    – Elder Geek
    Commented Jan 10, 2017 at 21:34

I found this gtk+-2 era tutorial https://wiki.gnome.org/Attic/GnomeArt/Tutorials/IconThemes, which explains the purpose of each field in an icon index.theme file. You can read the entire document but here are the most relevant sentences.

To begin making your theme, create a folder of the same name as you wish to call your theme, or by copying another theme as suggested above, and then you will be ready to start setting up the theme. The most important aspect of the icon theme is index.theme, an ini style configuration file which describes the theme in various sections. The main and most important section is broken down as follows: [...]

This section describes the layout of the theme in a very simple fairly intuitive way

Name = ThemeName
this field represents the name of the theme as should be displayed in the icons section of the Gnome Theme Manager, it is very important that the themes folder name matches this field

Comment = This is the theme comment
this field represents the comment of the theme as is sometimes displayed in Gnome Theme Manager

Directories = iconsize1/iconcategory1, iconsize1/iconcategory2, iconsize2/iconcategory1
this field represents the directories which contain the actual icons

Inherits = RootTheme
this field represents the root theme from which this theme inherits. If the theme does not supply a particular icon, GNOME will look in this root theme for icons before falling back on the system defaults.

Each directory as listed in the IconTheme section will also need its own section to describe icon size and type :

this section describes the characteristics of the icons located in this directory

Size = IconSize
this field represents the size of the icons located in this directory if they are bitmap icons (PNG or XPM), or the default scale if they are scalable icons (aka SVG)

MinSize = IconSize
this field represents the mimimum size that scalable icons (SVG) located in this directory can be scaled to.

MaxSize = IconSize
this field represents the maximum size that scalable icons (SVG) located in this directory can be scaled to.

Threshold = SizeThreshold==
this field represents the maximum size threshold that bitmap icons (PNG/XPM) located in this directory be used for if the icon type is Threshold.

Context = IconCategory
this field represents the category or context in which these icons are used. This value can be FileSystems (for Folder or HardDrives), Emblems, Applications, Devices, or MimeTypes

Type = IconType
this field represents the type of icons located in this directory, it can be Scalable for Scalable Icons (SVG), Threshold or Fixed(I have seen Scaled used as well, is this valid?!) for Bitmap Icons(PNG or XPM)


You can find a document here. I don't know how up to date it is though. It discusses the structure of the file, the possible keys that are allowed and their descriptions.

If you do have the time try joining #gtk+ and #gnome-design on IRC. They may be able to answer your queries better. See here for learning how.

  • I have already checked the link that you mentioned. But, the link not specified what should be there must and what should not, what stands for possible definition, etc.
    – Kiran
    Commented Jan 6, 2017 at 15:42
  • Then I think you'll have to contact someone who writes themes. You can find the authors of a lot of themes on Reddit's /r/unixporn community. Commented Jan 7, 2017 at 5:15

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .