Common Patterns

This section shows practical examples for common font search tasks.

Finding Monospace Fonts

Monospace fonts are useful for code editors, terminals, and tabular data. Use spacing=100 to find monospace fonts:

import fontconfig

# Find the best monospace font
font = fontconfig.match(properties={"spacing": 100})
if font:
    print(f"Monospace font: {font['family']}")
    print(f"File: {font['file']}")

# List all monospace fonts
mono_fonts = fontconfig.list(
    properties={"spacing": 100},
    select=("family", "file")
)

print(f"Found {len(mono_fonts)} monospace fonts:")
for font in mono_fonts[:10]:  # Show first 10
    print(f"  {font['family']}")

The spacing property values are:

0 = proportional
100 = monospace
110 = charcell

Finding Fonts by Language Support

Find fonts that support specific languages using the lang property:

import fontconfig

# Find fonts with Japanese support
japanese_fonts = fontconfig.list(
    properties={"lang": ["ja"]},
    select=("family", "file")
)

print(f"Fonts with Japanese support: {len(japanese_fonts)}")
for font in japanese_fonts[:5]:
    print(f"  {font['family']}")

# Find fonts supporting multiple languages
multilang = fontconfig.match(properties={"lang": ["zh-cn", "ja", "ko"]})
if multilang:
    print(f"CJK font: {multilang['family']}")

Common language codes:

en = English
zh-cn = Simplified Chinese
zh-tw = Traditional Chinese
ja = Japanese
ko = Korean
ar = Arabic
he = Hebrew
ru = Russian

Finding Bold and Italic Variants

Search for specific font styles using weight and slant properties:

import fontconfig

# Find bold variant
bold_font = fontconfig.match(properties={
    "family": "Arial",
    "weight": 200  # Bold
})

# Find italic variant
italic_font = fontconfig.match(properties={
    "family": "Arial",
    "slant": 100  # Italic
})

# Find bold italic
bold_italic = fontconfig.match(properties={
    "family": "Arial",
    "weight": 200,  # Bold
    "slant": 100    # Italic
})

if bold_italic:
    print(f"Bold Italic: {bold_italic['style']}")
    print(f"File: {bold_italic['file']}")

Weight values:

0 = Thin
40 = Light
80 = Normal/Regular (default)
200 = Bold
210 = Black/Heavy

Slant values:

0 = Roman (upright)
100 = Italic
110 = Oblique

Checking if a Specific Font Exists

Check whether a particular font is installed and get fallbacks if not:

import fontconfig

def find_font_or_fallback(family_name, fallbacks=None):
    """Find a font by family name with optional fallbacks."""
    if fallbacks is None:
        fallbacks = []

    # Try each font in order
    for family in [family_name] + fallbacks:
        font = fontconfig.match(properties={"family": family})
        if font and font.get('family') == family:
            return font

    # Return any matched font as last resort
    return fontconfig.match()

# Example usage
font = find_font_or_fallback(
    "Helvetica",
    fallbacks=["Arial", "Liberation Sans", "sans-serif"]
)

if font:
    print(f"Using: {font['family']}")
    print(f"File: {font['file']}")

Note: The match() function always returns a font (even if the exact family isn’t found), so check if the returned family matches what you requested.

Finding System Default Fonts

Get the system’s default fonts for common font families:

import fontconfig

# Get default sans-serif font
sans = fontconfig.match(properties={"family": "sans-serif"})
print(f"Default sans-serif: {sans['family']}")

# Get default serif font
serif = fontconfig.match(properties={"family": "serif"})
print(f"Default serif: {serif['family']}")

# Get default monospace font
mono = fontconfig.match(properties={"family": "monospace"})
print(f"Default monospace: {mono['family']}")

# Get all details
print(f"\nSans-serif details:")
print(f"  Family: {sans['family']}")
print(f"  Style: {sans['style']}")
print(f"  File: {sans['file']}")

The generic family names (sans-serif, serif, monospace) are special aliases that fontconfig resolves to the system’s preferred fonts.

Finding Fonts with Color/Emoji Support

Modern color fonts and emoji fonts can be found using the color property:

import fontconfig

# Find fonts with color support
color_fonts = fontconfig.list(
    properties={"color": True},
    select=("family", "file", "fontformat")
)

print(f"Color fonts available: {len(color_fonts)}")
for font in color_fonts:
    print(f"  {font['family']} ({font.get('fontformat', 'unknown')})")

# Find best emoji font
emoji_font = fontconfig.match(properties={"color": True})
if emoji_font:
    print(f"\nEmoji font: {emoji_font['family']}")
    print(f"File: {emoji_font['file']}")

Common color font formats include:

CBDT/CBLC = Color bitmap (used in Noto Color Emoji)
SBIX = Apple color emoji format
COLR = Microsoft layered color format
SVG = SVG-in-OpenType

Finding Variable Fonts

Variable fonts contain multiple style variations in a single file:

import fontconfig

# Find variable fonts
variable_fonts = fontconfig.list(
    properties={"variable": True},
    select=("family", "file", "fontvariations")
)

print(f"Variable fonts: {len(variable_fonts)}")
for font in variable_fonts[:10]:
    print(f"  {font['family']}")
    if 'fontvariations' in font:
        print(f"    Axes: {font['fontvariations']}")

The fontvariations property shows available variation axes (like weight, width, slant, optical size).

Getting Font File Paths

Extract font file paths and handle fonts with multiple faces:

import fontconfig

# Get font file path
font = fontconfig.match(":family=Arial")
if font:
    filepath = font['file']
    index = font.get('index', 0)

    print(f"Font file: {filepath}")
    print(f"Face index: {index}")

    # Use with font libraries
    # freetype_face = freetype.Face(filepath, index)
    # pil_font = ImageFont.truetype(filepath, size=12)

# Get all files for a font family
family_fonts = fontconfig.list(
    properties={"family": "Arial"},
    select=("family", "style", "file", "index")
)

print(f"\nAll Arial variants:")
for font in family_fonts:
    print(f"  {font['style']}: {font['file']} (index {font.get('index', 0)})")

Note: The index property is important for TrueType Collection (TTC) files that contain multiple font faces in one file. It defaults to 0.

Query fonts by family name (deprecated)

Deprecated since version 0.3.0: Use list(), match(), or sort() instead.

The legacy fontconfig.query() function is still available but deprecated:

import fontconfig

# Old way (deprecated)
fonts = fontconfig.query(
    where=":family=Arial",
    select=("family", "style", "file", "lang")
)

# New way (recommended)
fonts = fontconfig.list(
    pattern=":family=Arial",
    select=("family", "style", "file", "lang")
)