gtk-update-icon-cache-3.0

gtk-update-icon-cache-3.0 [OPTIONS...] ICON_THEME_DIR

ICON_THEME_DIR
    The path to the icon theme directory to be cached.

--force, -f
    Force the update of the cache file, even if it appears to be up-to-date.

--quiet, -q
    Suppress non-error messages during the cache update process.

--ignore-theme-dir
    Do not write the icon-theme.cache file directly into the theme directory. This option is typically used when the cache is managed externally, e.g., by a system-wide cache directory.

--index-only
    Only update or write the index.theme data within the cache, without including all icon data. Useful for themes that primarily rely on index.theme for structure.

--only-scalable
    Include only scalable icons (e.g., SVG files) in the cache. Non-scalable (bitmap) icons will be ignored.

--validate
    Validate the existing cache file for consistency and integrity.

--version
    Display the version information for the command.

--help
    Show a brief help message and exit.

gtk-update-icon-cache-3.0 is a utility designed to create or update the icon theme cache file for GTK+ 3.x icon themes. This cache, typically named icon-theme.cache, resides within an icon theme directory and significantly speeds up icon lookup and loading times for GTK 3 applications. Without this cache, applications would have to scan the entire icon theme directory every time they need an icon, leading to performance bottlenecks.

The command scans a specified ICON_THEME_DIR, collects information about all icons present, and generates a binary cache file. This cache includes paths, sizes, and other metadata about the icons. It is crucial for proper icon rendering in GTK 3 environments. This utility is typically invoked by package managers, theme installers, or users after installing new icon themes or updating existing ones to ensure the cache is up-to-date and reflects the current state of the icon files. It specifically targets the GTK 3 API version, ensuring compatibility with applications built against that library.

This command is specifically designed for GTK+ 3.x icon themes. For older GTK+ 2.x themes, the gtk-update-icon-cache command (without the -3.0 suffix) should be used. For newer GTK+ 4.x themes, gtk-update-icon-cache-4.0 is the appropriate utility. Running this command on a directory not containing a valid GTK+ 3 theme (specifically, an index.theme file) may result in an error or an incomplete cache. Ensure that the user running the command has write permissions to the ICON_THEME_DIR to successfully create or update the icon-theme.cache file.

The generated cache file, named icon-theme.cache, is typically found directly inside the ICON_THEME_DIR. For system-wide themes, this could be paths like /usr/share/icons/<theme_name>/, and for user-specific themes, ~/.local/share/icons/<theme_name>/.

Every valid GTK icon theme directory must contain an index.theme file. This file acts as a configuration file for the icon theme, providing metadata such as the theme's name, description, and inheritance hierarchy. gtk-update-icon-cache-3.0 relies on this file to properly identify and process the icon theme.

The gtk-update-icon-cache utility family emerged as a crucial component of the GTK+ toolkit to optimize icon loading. The original gtk-update-icon-cache was for GTK+ 2.x. As GTK+ evolved to version 3.x, API changes necessitated a separate, version-specific utility, leading to the creation of gtk-update-icon-cache-3.0. This separation ensures backward compatibility while allowing the toolkit to introduce new features and optimizations without breaking older applications. Its primary development focus has always been on improving performance and reliability for icon display within GTK-based desktop environments and applications.

gtk-update-icon-cache(1), gtk-update-icon-cache-4.0(1), update-icon-caches(8), gdk-pixbuf-query-loaders(1), xdg-desktop-menu(1)