gtk-update-icon-cache-3.0
Update GTK+ icon theme cache
SYNOPSIS
gtk-update-icon-cache-3.0 [OPTION...] <icon-directory>
PARAMETERS
-f, --force
Overwrite existing cache file even if unchanged
-i, --ignore-theme-index
Ignore directories named index.theme
-I, --index-only
Only scan directories named index.theme
-c, --include-image-data
Embed image data directly in the cache
-t, --source-dir=DIR
Use DIR for uninstalled theme sources
-q, --quiet
Suppress non-fatal error messages
-h, --help
Display help and exit
--version
Output version information and exit
DESCRIPTION
gtk-update-icon-cache-3.0 is a utility from the GTK+ 3.0 toolkit that generates a binary cache file (icon-theme.cache) for scalable icons in an icon theme directory. This cache dramatically speeds up icon loading in GTK+ applications by precomputing icon directories, symbolic links, and thumbnail data, avoiding repeated filesystem scans at runtime.
Icon themes are typically installed in /usr/share/icons/, ~/.icons/, or ~/.local/share/icons/. After adding or modifying icons (especially SVGs), running this command rebuilds the cache to make new icons immediately available. It supports embedding image data for faster access and handles theme indexes.
The tool scans subdirectories for icons matching freedesktop.org standards, prioritizing scalable formats. It's essential for theme developers and system administrators maintaining custom icon sets. Without an up-to-date cache, applications may fail to display icons correctly or experience performance issues.
Common usage follows icon theme installation via package managers, which often invoke it automatically. Manual invocation ensures consistency across users or systems.
CAVEATS
Requires write permissions to icon-directory; run as root for system themes. Cache file is icon-theme.cache unless overridden. Fails silently on invalid directories unless verbose.
EXAMPLES
sudo gtk-update-icon-cache-3.0 /usr/share/icons/hicolor
gtk-update-icon-cache-3.0 -f -i ~/.icons/MyTheme
OUTPUT FILE
Generates icon-theme.cache in <icon-directory>. Symbolic link .icon-theme.cache.sha1 tracks changes.
HISTORY
Introduced with GTK+ 3.0 in 2011 by the GNOME project to optimize icon loading for the new scalable icon system. Evolved from GTK+ 2.x version; maintained in GTK 3.x until transition to libadwaita and GTK4.
