Rebuild Fontconfig Caches Safely with fc-cache

You will scan the configured font directories, rebuild the Fontconfig cache when needed, and verify that the command completed successfully. The examples use fc-cache from fontconfig 2.15.0-1.1ubuntu2 on this machine. Allow about ten minutes, including a little time to check an application after the scan.

You need a shell and the fontconfig package. Most checks can run as your normal user. Use elevated privileges only when you are deliberately rebuilding caches in system-owned directories. This guide does not install fonts, edit Fontconfig configuration, restart applications or remove cache files.

1. Confirm the installed command

Check which executable will run and record its version:

$ command -v fc-cache
/usr/bin/fc-cache
$ fc-cache --version
fontconfig version 2.15.0

The package revision and the program version are different pieces of information. The installed Ubuntu package is 2.15.0-1.1ubuntu2, while the command reports the upstream Fontconfig version. Options and output can differ on older distributions, so check the local help when writing a script for another host.

Checkpoint: if command -v finds nothing, install or repair the package through your normal system management process before continuing. Do not copy an unrelated fc-cache binary into /usr/local/bin just to make the check pass.

2. Scan the configured directories

With no directory argument, fc-cache uses the directories in the current Fontconfig configuration. It scans readable font files and creates or updates cache files used by Fontconfig applications:

$ fc-cache -v

The -v option displays status while the scan is running. The exact directory list and messages depend on the host, so do not compare the complete output character for character. A successful run returns status 0. Capture that status immediately if you need to use it in a script:

$ fc-cache -v
$ status=$?
$ printf 'fc-cache exit status: %s\n' "$status"
fc-cache exit status: 0

The command writes cache data, so the scan is not merely a diagnostic. It does not change the font files themselves. If a program was already running, restart that program or use its own font reload facility before judging whether a newly installed font is visible.

3. Rebuild only system-wide caches

Use -s when the task is specifically about system-wide directories and should omit font directories under your home directory:

$ fc-cache --system-only --verbose

This is normally the right boundary for a machine-wide maintenance job. Run it as your normal user first. If it reports that it cannot write a system cache, rerun the same command with the privilege required by the host:

$ sudo fc-cache --system-only --verbose

sudo is not a general prerequisite for fc-cache. It grants permission to write protected cache locations, but it does not install fonts or repair a broken Fontconfig configuration. Review the directories in the verbose output before accepting a privilege prompt.

Checkpoint: repeat the command without sudo after the privileged scan. A successful unprivileged read is useful evidence that the cache files are present and readable, although it does not prove that every application has reloaded them.

4. Force a fresh scan when timestamps are misleading

By default, Fontconfig can skip a cache that appears current. Use -f, or --force, when font files or directory metadata changed in a way that left the cache looking current:

$ fc-cache --force --verbose /usr/share/fonts

The directory argument limits the scan to that directory and its configured handling, rather than asking for every configured directory. Replace /usr/share/fonts with a real directory that contains the fonts you intend to refresh. Check it before running:

$ test -d /path/to/font-directory && printf '%s\n' 'directory exists'
$ find /path/to/font-directory -maxdepth 1 -type f -print

Do not use a guessed path and then treat a zero exit status as proof that it contained the intended fonts. The -E option makes an empty target an error:

$ fc-cache --error-on-no-fonts /path/to/font-directory
$ printf 'fc-cache exit status: %s\n' "$?"

For automation, combine -E with a known directory and stop when the status is non-zero. The manual describes a non-zero result as a cache generation failure; an empty directory with -E is one deliberate way to trigger that failure.

5. Use a sysroot for an offline filesystem tree

When preparing a mounted image or staging tree, -y or --sysroot prepends a directory to the paths that fc-cache scans. This lets you target the tree without treating its fonts as part of the running host:

$ sudo fc-cache --sysroot=/mnt/target-root --system-only --verbose

Replace /mnt/target-root with the root of the mounted filesystem. Verify the mount before writing:

$ findmnt /mnt/target-root
$ test -d /mnt/target-root/usr/share/fonts && printf '%s\n' 'target font tree exists'

This option changes where the command looks and writes cache data. It does not mount the tree, chroot into it, or make the target system bootable. A wrong sysroot can populate the wrong filesystem, so stop if findmnt or the directory check does not identify the intended target.

6. Treat a full cache erase as a last resort

-r, also shown as --really-force in the installed help, erases existing cache files and then rescans. That is destructive to generated cache state and can make applications wait for a later rebuild. Do not use it as the first response to a missing font:

$ sudo fc-cache --really-force --system-only --verbose

Before using it, preserve the relevant configuration and record the target directories. Stop if the verbose output points at a different root or an unexpected cache location. There is no undo command for an erased cache, but the recovery is to run fc-cache again against the correct directories. Keep the original font files; fc-cache does not recreate fonts that have been removed.

7. Diagnose the common failures

A non-zero status means the cache generation did not complete successfully. Rerun with -v and read the first directory or permission error, rather than hiding it with a broad redirect:

$ fc-cache --verbose
$ printf 'fc-cache exit status: %s\n' "$?"

If a directory is missing or unreadable, check it without changing anything:

$ ls -ld /path/to/font-directory
$ find /path/to/font-directory -maxdepth 1 -type f -readable -print

If a cache scan succeeds but an application still cannot see a font, confirm that the font file is in the directory you scanned and restart the application. A successful cache build is not a guarantee that a font is valid, selected by the application's matching rules, or loaded by an already-running process.