Jump to content

Icons

From ArchWiki

Related articles

The freedesktop project provides the Icon Theme Specification, which applies to most linux desktop environments and tries to unify the look of a whole bunch of icons in an icon-theme. Freedesktop also provides the Icon Naming Specification, which defines a standard naming scheme for icons believed to be installed on any system. The default theme hicolor should include them all.

Installation

Icon themes

Tip It is recommended to install the hicolor-icon-theme package as many programs will deposit their icons in /usr/share/icons/hicolor/ and most other icon themes will inherit icons from the Hicolor icon theme.

From a package

Manually

If you cannot find a package for the icon theme you are looking for, you will need to install it manually.

  • Firstly, find and download your desired icon pack. Many different icon themes can be downloaded from the following sites: Opendesktop.org and Xfce-look.org.
  • Then navigate to the directory which contains the icon pack and extract it. Example tar -xzf ~/Downloads/icon-pack.tar.gz.
  • Move the extracted folder containing the icons.
    • /usr/share/icons/ (system-wide), or:
    • ~/.icons/ or ~/.local/share/icons/ (user only).
  • Optionally run gtk-update-icon-cache -f -t on the directory that you chose to update the icon cache.
  • Select the icon theme using the appropriate configuration tool for your desktop environment or window manager.
Tip
  • To update the icon theme, one may instead clone the repository into a different location (e.g. ~/Downloads/) by using git clone theme_repository.git. Afterwards, create a symbolic to that cloned folder in one of the paths mentioned earlier, depending on whether you want this icon theme to be available system-wide or only for the current user. That can be done by running ln -sf theme_path chosen_directory. Then, you may occasionally run git pull in the directory of the cloned repository to update the theme or to check for updates. This way, the updates will be applied easily without you having to download, extract and move themes.
  • Alternatively, create a package yourself, drawing inspiration from the PKGBUILDs of the packages linked at #From a package is also possible. See also VCS package guidelines.

Customization

A system always has an active theme. For KDE it is called "breeze" and for Gnome "Adwaita", but if nothing is chosen by the system the spec says that "hicolor" is the theme. Themes can also have parent themes; for example, "breeze-dark" inherits from "breeze", which means any icons it doesn't define are searched in "breeze".

Icons are named by short strings, for "checkmark" or "weather-snow-large" or "org.gnome.Showtime" which is passed by an app to the system to load a particular icon. When looking up an icon, if the active theme doesn't have it, its parent(s) are searched, and if none are found then "hicolor" is searched, since it is the fallback of all themes. Also, as a special case, some icons are named '-symbolic'; if these are not found the '-symbolic' is removed and searched again.

Not all files in a theme's folder are part of the theme. An icon-theme is defined by an index.theme file; you can see examples at /usr/share/icons/*/index.theme. Only sub-folders mentioned in that file count as part of the theme.

The subfolders are there to provide organization and, in the case of the numbered, different resolutions for different zoom levels, for example 

hicolor contents
/usr/share/icons/hicolor/
├── 1024x1024
├── 128x128
├── 16x16
├── 16x16@2
├── 192x192
├── 20x20
├── 22x22
├── 24x24
├── 24x24@2
├── 256x256
├── 32x32
├── 36x36
├── 40x40
├── 48x48
├── 512x512
├── 64x64
├── 72x72
├── 96x96
├── apps
├── icon-theme.cache
├── index.theme
├── scalable
|   ├── actions
|   ├── animations
|   ├── apps
|   ├── categories
|   ├── devices
|   ├── emblems
|   ├── emotes
|   ├── filesystems
|   ├── intl
|   ├── mimetypes
|   ├── places
|   ├── status
|   ├── stock
└── symbolic
    └── apps

but ultimately icons are in a flat namespace where the first match by name wins.

Confusingly, this means that looking up an icon has several places it could be, not all the same, but also many places cannot be and will silently be ignored if attempted. For example:

  • /usr/share/icons/Adwaita/symbolic/mimetypes/text-x-generic-symbolic.svg
  • /usr/share/icons/hicolor/scalable/actions/text-x-generic-symbolic.svg

are both the icon 'text-x-generic-symbolic', even though one is under symbolic/mimetypes/ in the "Adwaita" theme and the othelr is under scalable/actions/ in the "hicolor" theme. But

  • /usr/share/icons/breeze/scalable/actions/text-x-generic-symbolic.svg

will never be used by anyone, because breeze/index.theme does not define scalable/actions as part of itself.

Icons and emblems

If you have deduced the name of an icon you would like to customize, xdg-icon-resource can be used. This will resize and copy the icon to $HOME/.local/share/icons/. With this method, custom emblems can also be added. Examples: 

$ xdg-icon-resource install --size 128 --context emblems archuser-example.png # add as emblem
$ xdg-icon-resource install --size 128 archuser-example.png # add as normal icon

This only works for raster icons (.png and .xpm). For vector graphics (.svg), or just to understand better what is going on, the structure under ~/.local/share/icons can be created manually. To replace an icon, search for it in /usr/share/icons/; most are in /usr/share/icons/hicolor since that is the fallback theme so it is also where apps tend to install their icons. Once you find the image you want to replace, suppose for example /usr/share/icons/hicolor/scalable/actions/xsi-edit-find-symbolic.svg, create a local version, swapping ~/.local/share/icons for /usr/share/icons. That is to say: 

$ mkdir -p ~/.local/share/icons/hicolor/scalable/actions/
$ cp your-new-symbol.svg ~/.local/share/icons/hicolor/scalable/actions/xsi-edit-find-symbolic.svg

If you only have one then it does not matter which folder it is in, and your ~/.local copy will take precedence so long as it is one of the folders mentioned by the theme's icon.theme file.

You may need to log out to apply the new icon each time you change it, depending on what apps use it.

File naming is extremely precise with icon themes and a mistake will generally not present with any feedback except for the icon not changing, so triple-check spelling if it is not working.

To debug what icon is being loaded currently on your system, at least when loaded via Gtk: 

detect-icon.py
#!/usr/bin/env python3

import sys
import gi
gi.require_version('Gtk', '3.0');
from gi.repository import Gtk;
icon_theme = Gtk.IconTheme.get_default(); 

for icon_name in sys.argv[1:]:
  icn = icon_theme.lookup_icon(icon_name, 48, 0)
  if icn:
    print(icn.get_filename())
  else:
    print('Icon Not Found')


Mime type icons

File managers do not rely on the traditional mime type which file --mime outputs. Instead definitions from /usr/share/mime/ are used. Calling an icon according to the definition found there and copying it to ~/.local/share/icons/ will cause the file manager to display the custom mime type icon. This command illustrates the method to create a custom icon for the keepass database files (.kdb): 

$ sed -En 's/(.*)\/(.*)\:.*.kdb.*/\1-\2/p' /usr/share/mime/globs
application-x-keepass2

Rename your icon according to this output: 

$ xdg-icon-resource install --size 128 --context mimetypes application-x-keepass2.png

Custom Themes

Finally, if you have created a lot of changes to your theme you might consider packaging it as its own theme. To do this, make a folder and add an index.theme to it that _inherits_ from the theme you are customizing; for example, to customilze KDE's default dark theme: 

index.theme
[Icon Theme]
Name=ICONPACK NAME
Comment=ICONPACK DESCRIPTION
Inherits=breeze-dark

Add icons to this, following the structure of the original theme as above.

You can put your theme under ~/.local/share/icons/$YOUR_THEME, and then it should be available to pick from your desktop environment's appearance settings, or zip it up and share it with other people!

fstab / gvfs

According to this document file managers using GVFS (like GNOME Files or Thunar) can display icons for custom locations, like NFS shares. All you need are some extended mount options inside /etc/fstab with icon names supported by your selected icon theme: 

/etc/fstab
hostname:/ /mnt/ nfs4 defaults,_netdev,user,rw,exec,comment=x-gvfs-show,x-gvfs-name=Network%20Attached%20Storage,x-gvfs-icon=network-server,x-gvfs-symbolic-icon=network-server,timeo=14 0 0