Choose and Inspect Fonts Reliably with fc-match

Use fc-match to answer a practical question: which installed font will Fontconfig select for a request such as sans-serif, English text, or bold text? You will learn how to inspect the first choice, list alternatives, and produce stable machine-readable fields for scripts.

Time and prerequisites: allow about 10 minutes. You need a shell, the fontconfig package, and at least one installed font. These examples only read Fontconfig's configuration and make no system changes, so they do not need sudo. The output below was checked with fontconfig 2.15.0.

1. Check the command and package version

Start by confirming that the command is installed. The short option and long option are equivalent here.

fc-match --version
dpkg-query -W -f='${Package} ${Version}\n' fontconfig

On the machine used for this guide, the first command reports fontconfig version 2.15.0 and the package is fontconfig 2.15.0-1.1ubuntu2. Package version strings differ between distributions. If the command is missing, install Fontconfig through your distribution's normal package manager, then repeat this check. Installing a package is a separate, privileged operation and is deliberately not included in the read-only examples here.

Checkpoint: version confirmed

You can continue when fc-match --version prints a version instead of a command-not-found error.

2. Find the best match for a family request

Pass a pattern as the first non-option argument. A generic family such as sans asks Fontconfig for a sans-serif match. With no element argument, the normal output contains a short file name, family and style.

fc-match sans

A typical result on this host is:

DejaVuSans.ttf: "DejaVu Sans" "Book"

The selected file is not a promise that every machine will choose the same font. Fontconfig uses the fonts and configuration available on the current system, and matching also considers the request. Treat the result as an answer about this host, not as a portable font name.

If you omit the pattern, fc-match matches an empty pattern. That can still produce a result, but it is rarely what you want in a script or diagnostic note. State the family or other requirement explicitly so another reader can reproduce the query.

3. Add language and style requirements

Fontconfig patterns can include properties separated by colons. The installed manual gives language and weight examples, and these are useful when a generic family alone is too broad.

fc-match 'sans:lang=en'
fc-match 'sans:lang=en:weight=bold'

On this host the bold request returns:

DejaVuSans-Bold.ttf: "DejaVu Sans" "Bold"

Quote the complete pattern. The quotes keep the shell from treating the pattern as separate words and make the command easier to extend. A common distraction is reading a generic result as if it were a requested style: sans alone does not mean bold, italic, or a particular language.

Checkpoint: request matches the requirement

Run the query again with the exact family, language, and style your application needs. If the result does not have the expected family or style, inspect the candidates in the next step instead of assuming the first result is a configuration error.

4. Compare the sorted candidates

Use --sort, or its short form -s, to display the best matches in sorted order rather than only the first match.

fc-match --sort sans | head -n 5

The first five lines on this host are:

DejaVuSans.ttf: "DejaVu Sans" "Book"
DejaVuSans-Bold.ttf: "DejaVu Sans" "Bold"
DejaVuSans-Oblique.ttf: "DejaVu Sans" "Oblique"
DejaVuSans-BoldOblique.ttf: "DejaVu Sans" "Bold Oblique"
NimbusSans-Regular.otf: "Nimbus Sans" "Regular"

head only shortens what is displayed; it does not alter Fontconfig's result. For an unpruned sorted list, use --all or -a:

fc-match --all sans | head -n 5

Do not confuse these modes. --sort displays the sorted best matches, while --all displays the sorted list without pruning. Both can produce many lines, so redirecting them to a file is reasonable for investigation. No files are changed unless you explicitly add shell redirection such as > candidates.txt.

5. Extract fields for a script

Human-readable output is useful at a terminal but awkward to parse because it contains punctuation and several fields on one line. Use --format, or -f, with Fontconfig field substitutions. A newline escape keeps each selected property on its own line.

fc-match --format='%{file}\n%{family}\n%{style}\n' 'sans:lang=en:weight=bold'

The checked result is:

/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf
DejaVu Sans
Bold

This is safer for a small shell script than splitting the default display at spaces. Still, treat the output as data: font paths and family names come from the local configuration, so do not pass an extracted path to a privileged command without validating it for the job at hand.

6. Diagnose a surprising result

First rerun the exact pattern without a pipeline, then compare it with --sort. This separates a genuinely different match from a display mistake caused by head or a shell pipeline.

fc-match 'sans:lang=en:weight=bold'
fc-match --sort 'sans:lang=en:weight=bold' | head -n 10

For deeper inspection, ask for the whole font pattern:

fc-match --verbose 'sans:lang=en:weight=bold'

Verbose output is intentionally large. Use it at the terminal or save it to a deliberately named temporary file; do not paste it into a configuration file. If a script needs a value, return to --format and request only the fields it actually consumes.

Done means

• fc-match --version identifies the installed Fontconfig version.
• You can query a generic family and understand that the first result is host-specific.
• You can add lang and weight properties without losing the pattern to shell word splitting.
• You can distinguish --sort from the unpruned --all list.
• Your script uses --format when it needs a file, family, or style value rather than parsing display text.