Inspect Fontconfig Cache Files with fc-cat

When Fontconfig behaves oddly, fc-cat lets you read the cache it is actually using, without touching your fonts or rebuilding anything. You will check which fonts a directory cache describes and investigate a single cache file. The examples use Fontconfig 2.15.0 from Ubuntu package fontconfig 2.15.0-1.1ubuntu2, and take about ten minutes.

1. Check the installed command

Confirm that the command you will run is the one on your path. This is a read-only check:

$ command -v fc-cat
/usr/bin/fc-cat
$ fc-cat --version
fontconfig version 2.15.0
$ dpkg-query -W -f='${Package} ${Version}\n' fontconfig
fontconfig 2.15.0-1.1ubuntu2

The manual page describes -r, -v, -V and -h. The installed help also shows their long forms: --recurse, --verbose, --version and --help. Prefer the long forms in scripts when they make the intent clearer.

Checkpoint: if fc-cat --version fails, stop here and repair the package through your normal system-management process. Diagnosing that failure does not need a cache rebuild.

2. Read the cache for one font directory

Give fc-cat a font directory when you want the cache associated with it. Use a directory that exists on your machine; this common system path makes a good first test:

$ test -d /usr/share/fonts/truetype/dejavu && echo directory-found
directory-found
$ fc-cat /usr/share/fonts/truetype/dejavu | head -n 2
"DejaVuMathTeXGyre.ttf" 0 "DejaVu Math TeX Gyre:familylang=en:style=Regular:..."
"DejaVuSans-Bold.ttf" 0 "DejaVu Sans:familylang=en:style=Bold:..."

Each line describes one font entry in Fontconfig's ASCII representation. The fields and ordering are data from the local cache, so do not write a script that assumes a particular line length. The output can be long, which is why head helps for a first look.

The directory argument does not scan font files afresh. It asks Fontconfig to read the cache related to that directory. If the cache is missing or stale, run fc-cache as a separate step, because fc-cat is an inspection tool and does not repair anything.

3. Inspect a known cache file directly

Fontconfig cache files commonly live under /var/cache/fontconfig and, on this installation, have names ending in .cache-9. List candidates without changing anything:

$ find /var/cache/fontconfig -maxdepth 1 -type f -name '*.cache-*' | head
/var/cache/fontconfig/e52a45a1c8c8fe895fc0fc8c4e6999b8-le64.cache-9
/var/cache/fontconfig/0bd3dc0958fa2205aaaa8ebb13e2872b-le64.cache-9

Choose one path from your own output, then pass it as a single argument:

$ CACHE_FILE='/var/cache/fontconfig/REPLACE_WITH_A_CACHE_FILE'
$ test -r "$CACHE_FILE" && echo readable
readable
$ fc-cat "$CACHE_FILE" | head -n 3
"DejaVuMathTeXGyre.ttf" 0 "DejaVu Math TeX Gyre:familylang=en:style=Regular:..."

Replace the placeholder with a real path before running it. Quoting the variable stops whitespace or shell metacharacters in a path being interpreted by the shell.

Tip: a cache file may be empty, or may describe a directory you did not expect. That is evidence to investigate, not a reason to edit the file by hand.

4. Add context with verbose output

Use --verbose when the font records alone do not tell you which directory and cache file were selected:

$ fc-cat --verbose "$CACHE_FILE" | head -n 5
Directory: /usr/share/fonts/cmap/adobe-japan2
Cache: /var/cache/fontconfig/e52a45a1c8c8fe895fc0fc8c4e6999b8-le64.cache-9
--------
<empty>

The directory, cache filename and records depend on which file you selected. An empty cache is still a valid result for an inspected cache file. Read the header lines first, then decide whether that directory matters to your problem.

Checkpoint: you should now be able to answer two separate questions: which cache file was read, and what font records it contains. If you cannot, rerun with --verbose rather than guessing from the hashed filename.

5. Recurse only for a tree-wide view

Use --recurse when the argument is a directory tree and you want related subdirectories included:

$ fc-cat --recurse /usr/share/fonts | head -n 5
"X11" 0 ".dir"
"cMap" 0 ".dir"
"cmap" 0 ".dir"
"opentype" 0 ".dir"
"truetype" 0 ".dir"

Without --recurse, the command focuses on the cache for the directory you supplied. With it, output can become very large and include entries from many unrelated font families. Start with a narrow directory, pipe to a pager or use head, and widen the search only when the result is useful.

Tip: recursion is not cache creation. It changes how much existing cache data fc-cat reads; it does not scan every font or write new cache files.

6. Diagnose the common traps

If the command prints no useful records, check the argument type and permissions first:

$ ls -ld /path/to/font-directory
$ test -r /path/to/font-directory && echo readable
$ find /path/to/font-directory -maxdepth 1 -type f | head

A directory with no related cache, a cache with no entries, and a directory containing no font files are three different situations. Use --verbose to see which cache path Fontconfig selected. If the path is wrong, correct it; do not create an empty file with a cache-like name.

If you need to understand a font match rather than the cache contents, use the related Fontconfig tools named by the manual, such as fc-list, fc-match or fc-query. They answer different questions. fc-cat does not tell you which font a family request will choose, and a successful read does not prove that every application will render the font.

Warning: do not delete files under /var/cache/fontconfig as a first diagnostic step. Cache removal changes system state and may affect applications until the cache is rebuilt. If a rebuild is genuinely required, take a backup or follow your distribution's documented procedure, and verify applications afterwards. That is outside this read-only workflow.

Done means