August 25th 2018

eyecandy, linux

How To Install an Icon Theme from the Web, Manually

This question pops up every now and then, and I will try to answer it comprehensibly once and for all.


This text will not deal with installing icons or themes globally, to /usr/share/icons or /usr/share/themes. It will also not deal with installing them from the repositories (apt-get, synaptic, software center etc.). One should, however, always check first if the theme in question isn't available via package management!

This text will not deal with the various sites providing icon themes. It assumes you have downloaded the packed archive already.


The correct location for icon themes is ~/.local/share/icons (the '~' character represents the user's home directory), and GUI themes go to ~/.local/share/themes. The old locations ~/.icons and ~/.themes are still respected as far as I know.
To be safe, symlink one location to the other. Assuming the actual files are in ~/.local/share/icons, issue this command from a terminal: cd; ln -s .local/share/icons .icons (and accordingly for themes).

Extraction & After

I use my file manager's right-click => "Extract here" functionality. There's many different file formats and many different ways to go about the extraction, but the important thing is always the end result:

  • the folder conatining a theme is a direct subfolder of the icons or themes root folder. E.g. something like ~/.local/share/icons/fancy-theme/fancy-theme-1.0/ is invalid!
  • there must be an index.theme file inside the theme folder, right at its root.
  • the internal structure of the archive must remain intact: symlinks, permissions etc. have alook around to make sure that everything looks ok.

Some terminal output to illustrate (Flattr and ACYLS are both icon themes on my system):

=> $ pwd

=> $  tree -L 1 Flattr
├── actions
├── apps
├── categories
├── devices
├── emblems
├── index.theme
├── mimetypes
├── places
└── status

8 directories, 2 files

=> $ tree -L 1 ACYLS
├── GPL
├── credit
├── desktop
├── index.theme
├── scalable
└── scripts

3 directories, 4 files

As you can see the internal structure can differ, but index.theme is always there.


This file requires a little attention when you install manually.

Example from previously mentioned ACYLS:

[Icon Theme]
Comment= Simple icon theme that you can change color and other stuff on.

There can be a lot more in that file, but two entries are essential:

  1. Name: This is the name that will show up when you later select the icon theme, and this is the name that other themes will refer to in their "Inherits".
  2. Inherits: No icon theme is complete. There needs to be a mechanism to search for fallback icons when something is not available. It is possible to first choose inherits that go well with the icon theme, and only fall back to something like gnome or hicolor when that fails (this is what people really refer to when they say "Some icons are ugly"). Many icon themes are deliberately incomplete; they only provide a few differently styled icons (folders, panel icons) and largely depend on some "parent" icon theme.

When you manually install icon themes, you need to check these two values, and adapt them to what is actually available on your system.

Permissions & Symbolic Links & Broken Themes

Sometimes the extracted archives can have wrong ownership or permissions.
please compare the output of ls -al for e.g. your home directory, and the theme directory. In case something is off, try this:

=> $ cd ~/.local/share/icons
=> $ sudo chown -R "$(whoami)" fancy-theme
=> $ chmod -R 644 fancy-theme
=> $ chmod -R +X fancy-theme

Sometimes the symlinks (an extremely important part of every icon theme) can be broken. This is most likely the fault of the person who created the theme, and I know of no easy way of fixing it.

Needless to say, some of the themes found online are sub-standard. Don't get disappointed, just try something else.

Graphical Sudo/root Applications Don't Follow the Chosen Theme

This is a good thing, because it gives me an additonal visual clue that I'm running with superuser privileges now.
A few hacks to improve that situation are possible, but would go beyond the scope of this article. I only mention it to let people know that this is normal.