Read Fontconfig's Active Configuration with fc-conflist

When a font rule mysteriously does not apply, fc-conflist shows in seconds which Fontconfig files are processed and which are silently ignored. You will also see roughly where each file lands in the processing order, which turns a guessing game into a quick trace. That makes an unexpected rendering change far easier to investigate.

Allow about ten minutes. You need a shell and the fontconfig package. The examples here use Fontconfig 2.15.0 from package version 2.15.0-1.1ubuntu2. This is a read-only inspection: fc-conflist does not enable, disable, edit or delete configuration files, so it normally needs no elevated privileges.

1. Confirm the installed command

Start by checking which executable your shell will run and asking it for its version:

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

The package version and the program version usually travel together, but record both when reporting a configuration problem. Different distributions can backport changes while retaining a familiar upstream version.

Checkpoint: if command -v finds nothing, install or enable the Fontconfig package through your normal system-management process. Do not copy a binary from another machine just to continue this check.

2. Print the configuration list

Run the command without arguments:

$ fc-conflist
+ /etc/fonts/conf.d/10-hinting-slight.conf: Set hintslight to hintstyle
+ /etc/fonts/conf.d/10-scale-bitmap-fonts.conf: Bitmap scaling
+ /etc/fonts/conf.d/10-sub-pixel-rgb.conf: Enable sub-pixel rendering with the RGB stripes layout
- /usr/share/fontconfig/conf.avail/10-autohint.conf: Enable autohinter

Your list will be host-specific and may be much longer. Each line has a marker, a path, a colon and a description. A + means that Fontconfig processes the file. A - means that it is ignored. A missing description is reported as No description, which describes the file's metadata, not whether the file is active.

Do not read the marker as a recommendation. An ignored file can be a valid alternative configuration that is simply not selected on this machine. The command reports Fontconfig's current view; it does not change the selection.

For a long result, keep the output in the terminal or send it to a pager:

$ fc-conflist | less

If you redirect the output to a file, choose a new diagnostic filename. Shell redirection with > truncates an existing destination before fc-conflist runs:

$ fc-conflist > /tmp/fc-conflist.txt
$ sed -n '1,12p' /tmp/fc-conflist.txt

3. Separate active and ignored files

For a quick count, filter the markers rather than counting paths by hand:

$ fc-conflist | awk '/^\+ / { processed++ } /^- / { ignored++ } END { printf "processed=%d ignored=%d total=%d\n", processed, ignored, processed + ignored }'
processed=48 ignored=23 total=71

The numbers above are from the installed machine and are only an example. They change when packages add files or when the enabled links under /etc/fonts/conf.d change.

To inspect only ignored entries:

$ fc-conflist | awk '/^- / { print }'

On this system, many ignored entries are under /usr/share/fontconfig/conf.avail, while processed entries are under /etc/fonts/conf.d. Treat that as an observation, not a universal rule. Use the marker and the complete path as the evidence for the host you are troubleshooting.

Checkpoint: if a file you expected to be active has a - marker, stop here and inspect the exact path and its surrounding entries. Do not alter links or edit XML merely because a file appears in the list.

4. Use the order to trace a surprising rule

The output order resembles the order Fontconfig uses when processing the files. It is useful for a first-pass trace, but it is not a literal dump of every XML operation. The manual calls out one exception: when a file contains an <include> element, that file is shown after the subdirectories targeted by the include have been processed.

Start with the first active file that could explain the behaviour, then inspect the file named on that line:

$ fc-conflist | awk '/^\+ / { print; if (++n == 12) exit }'
$ sed -n '1,160p' /etc/fonts/conf.d/10-hinting-slight.conf

The second command is an example path. Replace it with a path from your own + line. Reading the XML is still read-only. Look for the family, language, preference or rendering rule that could affect your case, and then continue through later active files because later configuration can add or adjust behaviour.

A configuration file can be readable yet irrelevant if its marker is -. Conversely, an active file with No description can still contain a real rule. Do not use the description as a substitute for opening the file.

5. Check the command's failure signal

fc-conflist returns status 0 when parsing succeeds. The manual documents status 1 for parsing errors or when at least one font face cannot be opened. Capture the status immediately if you are putting the check in a script:

if fc-conflist > /tmp/fc-conflist.txt; then
    printf '%s\n' 'Fontconfig configuration parsed'
else
    status=$?
    printf 'fc-conflist failed with status %s\n' "$status" >&2
    exit "$status"
fi

Do not treat a non-zero result as proof that one particular configuration file is wrong. Read the diagnostic output, then check the paths and fonts involved. A permission or filesystem problem can be just as relevant as malformed XML.

For a deliberately harmless option check, use the built-in help:

$ fc-conflist --help
usage: fc-conflist [-Vh] [--version] [--help]
Show the ruleset files information on the system

The documented options are -V/--version and -h/--help. There is no option in this command for enabling a file, changing the search path or selecting a different configuration. Those are separate configuration tasks with their own change and rollback procedures.

6. Keep the investigation reversible

This workflow changes no Fontconfig state. If you created the temporary report, remove only that known file after you have finished reviewing it:

$ rm -- /tmp/fc-conflist.txt

That removal is optional and irreversible for the report itself, so retain it if someone else needs to compare the host's configuration. Do not run commands that remove entries from /etc/fonts/conf.d, edit files in /etc/fonts, or restart applications as part of this read-only check. If a change is required, make a backup, document the intended rule, and use the system's normal package or configuration-management rollback path.

Done means