Refresh a GTK Icon Theme Cache Without Guessing

Icons that will not refresh after a theme update usually come down to a stale cache, and gtk-update-icon-cache is the tool that rebuilds it. You will create a fresh cache for a GTK icon theme and confirm it can be read. Along the way you will see when to use --index-only, how to validate an existing cache, and why touching a system theme normally needs elevated privileges. Allow about ten minutes. You need a shell, the gtk-update-icon-cache package, and a theme directory that contains index.theme.

1. Check the installed command

Start with read-only checks. This machine has GTK 3.24.41, from Ubuntu package version 3.24.41-4ubuntu1.3. Option details differ between GTK releases, so keep that version number with any deployment notes.

$ command -v gtk-update-icon-cache
/usr/bin/gtk-update-icon-cache
$ gtk-update-icon-cache --version
gtk-update-icon-cache 3.24.41-4ubuntu1.3
$ dpkg-query -W -f='${Package} ${Version}\n' gtk-update-icon-cache
gtk-update-icon-cache 3.24.41-4ubuntu1.3

The command takes one positional argument: the path to the icon theme directory. That is not the path to a single PNG or SVG file. A normal theme directory has an index.theme at its top level and one or more subdirectories holding icons.

2. Inspect the theme before changing it

Choose a real theme path, then check its index and existing cache without writing anything. Replace /path/to/theme with the directory you actually intend to update:

$ THEME_DIR='/path/to/theme'
$ test -d "$THEME_DIR" && printf '%s\n' 'theme directory exists'
theme directory exists
$ test -r "$THEME_DIR/index.theme" && printf '%s\n' 'index.theme is readable'
index.theme is readable
$ ls -l "$THEME_DIR/index.theme" "$THEME_DIR/icon-theme.cache" 2>/dev/null

The last command may report that icon-theme.cache does not exist. That is not a failure if the theme has never been cached before. Without --ignore-theme-index, the utility refuses a directory that lacks index.theme, which catches a common mistake: pointing it at the parent /usr/share/icons directory, or at a single icon directory instead of a theme root.

3. Build the cache in a writable test copy

Test the command in a directory you own before updating a system-owned theme. Copying an existing theme costs a little disk space, but it gives you a reversible check and avoids half-completed writes under /usr/share:

$ TEST_ROOT="$(mktemp -d /tmp/gtk-icon-theme.XXXXXX)"
$ cp -a /usr/share/icons/hicolor "$TEST_ROOT/"
$ gtk-update-icon-cache --force "$TEST_ROOT/hicolor"
gtk-update-icon-cache: Cache file created successfully.
$ ls -l "$TEST_ROOT/hicolor/icon-theme.cache"
-rw-r--r-- 1 you you ... icon-theme.cache

--force tells the utility to overwrite an existing cache even when it looks current. It is useful for a deliberate rebuild, but it is still a write operation. The command scans the directory tree below the theme root and creates the cache there; it does not touch the original theme permanently in this test.

The exact owner, timestamp and byte count vary. What matters is exit status 0 and the presence of icon-theme.cache. If the command fails, leave the original theme alone and investigate the path or permissions before trying again.

4. Validate the generated cache

Use --validate to check an existing cache. It reads the cache and returns success or failure; it does not rebuild anything:

$ gtk-update-icon-cache --validate "$TEST_ROOT/hicolor"
$ printf 'validation status: %s\n' "$?"
validation status: 0
$ gtk-update-icon-cache --quiet --validate "$TEST_ROOT/hicolor"
$ printf 'quiet validation status: %s\n' "$?"
quiet validation status: 0

--quiet suppresses normal diagnostic output, useful in a script that only needs the exit status. Capture $? immediately: running another command first overwrites the status you were trying to inspect.

A failed validation is a reason to rebuild from the source theme, not to start deleting files at random. Keep the old cache until a replacement has passed validation. If you are testing a disposable copy, remove the temporary directory once you are done; do not apply that same cleanup habit to a shared icon directory.

5. Choose whether to include image data

The default cache includes both cached icon information and image data. Use --index-only when you specifically want to drop the image data, for example when a smaller index-only cache is part of a packaging decision:

$ gtk-update-icon-cache --force --index-only "$TEST_ROOT/hicolor"
gtk-update-icon-cache: Cache file created successfully.
$ gtk-update-icon-cache --validate "$TEST_ROOT/hicolor"
$ printf 'index-only validation status: %s\n' "$?"
index-only validation status: 0

The inverse spelling, --include-image-data, explicitly requests image data. Do not combine it with --index-only; they describe opposite cache contents. For an ordinary GTK theme, start with the default and reach for --index-only only once you have measured or documented a reason.

6. Update a system theme carefully

Once the test copy works, update the real theme. Writing inside /usr/share/icons normally requires elevated privileges, and this is the one state-changing command in the whole workflow:

$ sudo gtk-update-icon-cache --force /usr/share/icons/hicolor
gtk-update-icon-cache: Cache file created successfully.
$ sudo gtk-update-icon-cache --validate /usr/share/icons/hicolor

Do not use sudo for inspection or for a theme in your home directory. Do not run this during package installation, or while a package manager is replacing the same theme: a refresh is normally quick, but an application starting mid-update can see an old or missing cache.

7. Use source output only for a build step

--source NAME writes a C header declaration containing the cache. That is for a build or packaging workflow, not for refreshing the normal on-disk cache. Give it a clear constant name and an explicit output destination in a directory you control:

$ gtk-update-icon-cache --source gtk_theme_cache "$TEST_ROOT/hicolor" > "$TEST_ROOT/gtk-theme-cache.h"
$ test -s "$TEST_ROOT/gtk-theme-cache.h" && printf '%s\n' 'header written'
header written

Shell redirection creates or truncates the destination before the command runs, so use a new filename or a temporary file when the header matters. This option does not replace icon-theme.cache in the theme directory.

Common failure checks

• No theme index file: check that the argument is the top-level theme directory. Use --ignore-theme-index only for a deliberate non-theme cache experiment.
• Permission denied: use a writable test copy first, then use the privilege the real theme's ownership actually requires. Do not make the whole icon tree world-writable.
• Validation fails: confirm the cache belongs to the directory being checked, then rebuild from an intact theme copy. A cache from another theme is not a valid substitute.
• Icons still look stale: validate the cache, then restart the affected application. The cache feeds GTK's theme lookup; it is not a command to redraw an already-rendered window.