Blog
Fontconfig

Fontconfig

March 10, 2026·Abid
Abid

fontconfig

a low-level font configuration & customization library for unix-like operating system.

Features

  • font discovery
    • scans fonts in ~/.local/share/fonts or /usr/share/fonts/ directory
    • builds cache
  • font matching
    • when a application requests for font finds the best matching font installed
    • if it’s not found go for fallbacks
  • configuration
    • handles configurations via configuration files

Configuration

System-wide configuration:

  • /etc/fonts/fonts.conf
  • /etc/fonts/conf.d/

User-specific configuration (overrides system):

  • ~/.config/fontconfig/fonts.conf
  • ~/.config/fontconfig/conf.d/
  • ~/.config/fontconfig/conf.d/99-default-fonts.conf
<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "fonts.dtd">
<fontconfig>

  <!-- Sans-serif → SF Pro Text -->
  <alias>
    <family>sans-serif</family>
    <prefer>
      <family>SF Pro Text</family>
    </prefer>
  </alias>

  <!-- Serif → SF Pro Display -->
  <alias>
    <family>serif</family>
    <prefer>
      <family>Serif UI Text</family>
    </prefer>
  </alias>

  <!-- Monospace → Ioskeley Mono Nerd Font -->
  <alias>
    <family>monospace</family>
    <prefer>
      <family>Ioskeley Mono Nerd Font</family>
    </prefer>
  </alias>

  <!-- Ensure proper emoji fallback -->
  <match target="pattern">
    <edit name="family" mode="append_last">
      <string>Noto Color Emoji</string>
    </edit>
  </match>

  <!-- Ensure CJK fallback -->
  <match target="pattern">
    <edit name="family" mode="append_last">
      <string>Noto Sans CJK JP</string>
    </edit>
  </match>

</fontconfig>

Cheatsheet

Warning

This Cheatsheet is generated by ai for reference only.

# listing fonts 
fc-list # lists ALL installed fonts known to fontconfig.

fc-list : family # lists only font family names.

fc-list : family style # lists family + style (Regular, Bold, Italic, etc.).

fc-list | grep "JetBrains" # search for fonts matching a keyword.

fc-list | grep "FiraCode" # shows font file paths containing FiraCode.

fc-list :spacing=100 # lists only monospace fonts (100 = monospace).

fc-list :charset=0985 # lists fonts supporting Unicode character U+0985 (Bangla example).


# font matching 
fc-match monospace # shows which font will be used for "monospace".

fc-match sans # shows default sans-serif font.

fc-match serif # shows default serif font.

fc-match -v monospace # verbose output with full resolution details.

fc-match "monospace:weight=bold" # match monospace font with bold weight.

fc-match "sans:lang=bn" # match sans-serif font optimized for Bangla language.


# font metadata query 
fc-query /path/to/font.ttf
# Displays detailed metadata for a specific font file:
# family, style, weight, charset, spacing, etc.

# cache management 
fc-cache -fv
# Rebuilds font cache.
# -f = force rebuild
# -v = verbose output

# debugging 
FC_DEBUG=1 fc-match monospace # Enables basic debugging info for font matching.

FC_DEBUG=4 fc-match monospace # Higher debug level for deeper troubleshooting.


# installing fonts 
mkdir -p ~/.local/share/fonts # Creates user font directory (if it doesn't exist).

cp *.ttf ~/.local/share/fonts # Copies fonts to user directory.

fc-cache -fv # Rebuild cache after installation.

sudo cp *.ttf /usr/share/fonts/ # System-wide installation (requires root).

sudo fc-cache -fv # Rebuild system cache.
Last updated on
Tmux, the Window Manager for Terminal