Inspect and format font patterns with fc-pattern

You will use fc-pattern to see how Fontconfig parses a font request, inspect only the properties you need, and format selected values for a script. The examples use fontconfig 2.15.0, installed from Ubuntu's fontconfig package. Allow about ten minutes. You need a shell and a normal user account; none of these checks needs sudo or changes a configuration file.

1. Confirm the installed command

Start by checking which executable is being used and recording its version. This matters because the local manual page is older than the installed program, and the help text is the most direct description of the binary's accepted options.

$ command -v fc-pattern
/usr/bin/fc-pattern
$ fc-pattern --version
fontconfig version 2.15.0
$ fc-pattern --help
usage: fc-pattern [-cdVh] [-f FORMAT] [--config] [--default] [--verbose] [--format=FORMAT] [--version] [--help]

The help output continues with the pattern and element arguments. If command -v finds a different copy, repeat the examples with that executable and treat its version as authoritative. The command reads the Fontconfig configuration used by your account, but it does not write it.

2. Parse a named family and style

Pass a pattern as one shell argument. A colon separates the family from properties in the Fontconfig pattern syntax. This example asks for the DejaVu Sans family with a Bold style:

$ fc-pattern 'DejaVu Sans:style=Bold'
Pattern has 2 elts (size 16)
        family: "DejaVu Sans"(s)
        style: "Bold"(s)

The output is a parsed pattern, not a list of installed fonts and not a font match. In this case it shows two elements, family and style. The (s) marker is Fontconfig's value binding information. Keep the quotes around a pattern containing spaces so the shell does not split it.

You can also use the short family syntax when it is unambiguous:

$ fc-pattern 'DejaVu Sans:bold:lang=en' family style lang
Pattern has 2 elts (size 16)
        family: "DejaVu Sans"(s)
        lang: en(s)

That result is a useful warning: the word bold in this form is not displayed as a separate style element by the installed command. Use the explicit style=Bold form when you need to inspect the style property itself.

3. Limit the display to selected elements

After the pattern, add one or more element names. This keeps a large pattern readable and makes a quick diagnostic easier to compare:

$ fc-pattern 'DejaVu Sans:style=Bold' family style file
Pattern has 2 elts (size 16)
        family: "DejaVu Sans"(s)
        style: "Bold"(s)

file is absent because parsing a pattern does not select a particular installed font file. Do not treat a missing property as proof that a font is unavailable. If your aim is to find the best installed match, use the separate fc-match command and inspect its result there.

An empty pattern is valid and is the default when you omit the pattern argument:

$ fc-pattern
Pattern has 0 elts (size 0)
        (null):

This output is not an error. It means there are no explicitly parsed elements to display.

4. Apply substitutions only when you need them

By default, fc-pattern shows the parsed pattern. The --config or -c option performs Fontconfig configuration substitution, while --default or -d performs default substitution. These operations can expand or add values, so leave them out when you are checking the literal request:

$ fc-pattern --default 'sans-serif' family style size
Pattern has 2 elts (size 16)
        family: "sans"(s)
        size: 12(f)(s)

Here the default substitution adds a size of 12. Configuration substitution can expand the generic family according to the machine's configuration:

$ fc-pattern --config 'sans-serif' family
Pattern has 1 elts (size 16)
        family: "DejaVu LGC Sans"(w) "Noto Sans"(w) "DejaVu Sans"(w) ...

The full list is host-specific and can be long. The (w) values are weak alternatives, while (s) marks a strong value. Do not copy this machine's family list into a deployment rule. If output changes after a package or configuration update, first compare the version and active Fontconfig configuration.

5. Produce stable output for a script

Use --format or -f when a human-readable dump is too noisy. A format string can request a property with %{property} and can include an escaped newline:

$ fc-pattern --format='family=%{family};style=%{style};file=%{file};\n' 'DejaVu Sans:style=Bold'
family=DejaVu Sans;style=Bold;file=;

The empty file value is expected for the same reason as before: this command has parsed a pattern but has not matched it to a font file. Format output is useful for logs and simple shell checks, but do not assume every property exists. A missing value becomes an empty field in this example, so include labels or delimiters that make that case visible.

Quote the format string so the shell does not interpret its punctuation. If you need one value per line, keep the newline in the format string:

$ fc-pattern -f '%{family}\n%{style}\n' 'DejaVu Sans:style=Bold'
DejaVu Sans
Bold

6. Diagnose surprising results safely

First rerun without substitutions, then add --default and --config separately. This isolates whether a value came from the input, the default rules, or the configuration. Use a selected element list or a format string to avoid losing the relevant line in a long expansion.

An unrecognised element does not cause a non-zero exit status in the installed command; it can simply produce an empty pattern or no matching field. Check the spelling of the property and test the same request without the element filter. If you need to know whether a font is installed, remember that fc-pattern alone does not answer that question.

There is no recovery procedure because these examples are read-only. Do not edit system Fontconfig files merely to make one diagnostic output look different. Configuration changes affect other applications and should be made through your distribution's normal package or administrator workflow, with a tested rollback.