fontconfig-py

Python bindings to fontconfig based on Cython.

What is fontconfig? Fontconfig is a library for configuring and customizing font access on Unix-based systems. It helps applications locate installed fonts and select the best matching font based on criteria like family name, weight, slant, and language support. Instead of hardcoding font paths, applications use fontconfig to query the system's font database.

Currently, Linux and macOS are supported.

Install

Install from PyPI:

pip install fontconfig-py

Usage

Finding the best matching font

Use fontconfig.match() to find the single best font matching your criteria:

import fontconfig

# Find the best Arial font
font = fontconfig.match(":family=Arial:weight=200")
if font:
    print(font["family"], font["file"])

# Or using a properties dict
font = fontconfig.match(properties={"family": "Arial", "weight": 200})

Listing all matching fonts

Use fontconfig.list() to get all fonts matching a pattern:

import fontconfig

# List all English fonts
fonts = fontconfig.list(":lang=en", select=("family", "file"))
for font in fonts:
    print(font["family"], font["file"])

# List all available fonts
all_fonts = fontconfig.list()

Getting sorted font results

Use fontconfig.sort() to get fonts sorted by match quality:

import fontconfig

# Get Arial fonts sorted by match quality
fonts = fontconfig.sort(":family=Arial")
for font in fonts[:5]:  # Top 5 matches
    print(font["family"], font["file"])

Documentation

For detailed API documentation and advanced usage, visit fontconfig-py.readthedocs.io.

Features

This package offers several advantages over other fontconfig wrappers:

• Cython-based wrapper - High performance with Pythonic API
• Statically linked binary wheels - No runtime dependencies on fontconfig or freetype
• Cross-platform support - Linux and macOS wheels available
• Modern high-level API - Simple match(), list(), and sort() functions
• Continuous integration - Automated PyPI releases and testing
• MIT license - Permissive licensing

Other Python fontconfig wrappers

• fontconfig: CFFI bindings for fontconfig
• python_fontconfig: Python wrapper based on ctypes
• Python_fontconfig: Unmaintained Cython wrapper

Contributing

Contributions are welcome! Please see our Contributing Guidelines for details on:

• Setting up the development environment
• Running tests and code quality checks
• Submitting pull requests
• Code of conduct

For security vulnerabilities, please see our Security Policy.

License

This project is distributed under MIT license.

The binary wheels bundle fontconfig and freetype, which are distributed under their respective licenses. See NOTICE for details.