Rebuild Fontconfig Caches Safely with fc-cache

You installed a font and the application still cannot see it, so fc-cache is the tool that makes Fontconfig look again. This guide scans the configured font directories, rebuilds the cache when needed and checks that the command really finished. It uses fontconfig 2.15.0-1.1ubuntu2 and takes about ten minutes, including a check in an application afterwards.

• You need a shell and the fontconfig package.
• Privileges: most checks run as your normal user. Use elevated privileges only when you are deliberately rebuilding caches in system-owned directories.
• Out of scope: 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 things. 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.

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 the cache files Fontconfig applications use:

$ fc-cache -v

The -v option shows status while the scan runs. The directory list and messages depend on the host, so do not compare the output character for character. A successful run returns status 0. Capture it immediately if a script needs it:

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

The command writes cache data, so it is not merely a diagnostic. It does not change the font files themselves.

3. Rebuild only system-wide caches

Use -s when the task is about system-wide directories and should skip 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 the host requires:

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

4. Force a fresh scan when timestamps mislead

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

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

The directory argument limits the scan to that directory and its configured handling, instead of every configured directory. Replace /usr/share/fonts with a real directory containing the fonts you intend to refresh, and 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 it held 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' "$?"

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 fc-cache scans. That 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, and 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.

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 destroys generated cache state and can leave applications waiting for a later rebuild. Do not make it your first response to a missing font:

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

7. Diagnose the common failures

A non-zero status means cache generation did not complete. Rerun with -v and read the first directory or permission error, rather than hiding it behind 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 the scan succeeds but an application still cannot see a font, confirm the font file is in the directory you scanned and restart the application. A successful cache build does not guarantee that a font is valid, that the application's matching rules will select it, or that an already-running process has loaded it.