• build-essential provides gcc and g++ compilers needed for native gem extensions

• ruby-dev provides Ruby headers required for gem compilation

• git is required for fontist update and fontist repo commands

For RHEL/CentOS 7 or earlier, use yum instead of dnf.

This installs the Xcode Command Line Tools which include:

• clang compiler (compatible with gcc/g++)

• git command-line tool

• Required headers and libraries for native gem compilation

1. Install Ruby using RubyInstaller with DevKit (select the "Ruby+Devkit" version)

2. After installation, run the following in a command prompt to set up MSYS2:

   ridk install

   Select option 3 (MSYS2 and MINGW development toolchain) when prompted.

3. Install Git for Windows

On Linux systems, if you want to use fontist fontconfig update to make Fontist fonts available to other applications, install fontconfig:

Fontist depends on several gems that include native C/C++ extensions:

Fontist supports installing fonts to different named locations on a system.

There are three types of named locations:

fontist (default)

the Fontist font library, a per-user directory managed by Fontist

• By default located at ~/.fontist/fonts/{formula-key}/

• No administrative permissions required

• Fonts organized by formula to prevent naming conflicts

• Can be customized via FONTIST_FONTIST_FONTS_PATH environment variable or the fontist_fonts_path configuration option

user

the platform-specific user font directory used by the system

• No administrative permissions required

• Available to current user only

• macOS: ~/Library/Fonts/fontist

• Linux: ~/.local/share/fonts/fontist

• Windows: %LOCALAPPDATA%\Microsoft\Windows\Fonts\fontist

• By default, Fontist uses a subdirectory fontist within the user font directory to avoid cluttering the main font directory.

• Can be customized via FONTIST_USER_FONTS_PATH environment variable or the user_fonts_path configuration option

system

the platform-specific system font directory used by the system

• Requires administrative/sudo permissions

• Available to all users on the system

• macOS: /Library/Fonts/fontist

• Linux: /usr/local/share/fonts/fontist

• Windows: %windir%\Fonts\fontist

• The system location on macOS for supplementary fonts cannot be changed and is managed by the OS.

• By default, Fontist uses a subdirectory fontist within the system font directory to avoid cluttering the main font directory.

• Can be customized via FONTIST_SYSTEM_FONTS_PATH environment variable or the system_fonts_path configuration option

The default installation location can be configured:

The exact path where a font is installed depends on the chosen named location:

• For the fontist location, fonts are installed to the Fontist font library, which is by default at ~/.fontist/fonts/{formula-key}/, where {formula-key} is the unique key of the formula used to install the font (e.g., roboto/, lato/) to prevent filename conflicts between different font packages.

• For the user and system locations, fonts are installed to the standard font directories used by the operating system directly at the platform-specific user or system font directory as individual font files. Fontist will create a subdirectory named fontist within these directories to avoid cluttering the main font directory. macOS, Windows and Linux all support installing fonts in a subdirectory.

• For system location on macOS for supplementary fonts, the fonts are installed to to the proper OS-version-specific supplementary fonts directory (e.g. /System/Library/AssetsV2/com_apple_MobileAsset_Font{n}/). This is not configurable.

Fontist always searches for fonts in ALL locations regardless of where they were installed:

• System font directories (platform-specific)

• User font directories (platform-specific)

• Fontist font library directory

This means fonts installed by other applications or the operating system are automatically discovered and can be used by Fontist on font reindexing.

Fontist implements two types of caches to optimize performance and reduce redundant downloads:

• Download cache (~/.fontist/downloads): Font files downloaded by end users via fontist install

• Import cache (maintainer-only) (~/.fontist/import_cache): Font archives downloaded during formula imports

These caches can be managed using the fontist cache command.

The following commands will clear Fontist’s caches.

Clear download cache:

Clear import cache:

Fontist maintains an index of system fonts for fast lookups. The fontist index command provides tools to manage this index.

Rebuild the system font index from scratch:

With verbose output to see progress and statistics:

Build or update the index incrementally (faster than rebuild):

Display information about the current index:

Delete the system font index (will be rebuilt on next use):

All fontist index commands support these options:

-v, --verbose

Show detailed progress and statistics

-o, --output=PATH

Save index to specified path (for inspection)

The Fontist::Font.find interface can be used a find a font in your system.

It will look into the operating system specific font directories, and also the fontist specific ~/.fontist directory.

• If Fontist finds a font, then it will return the paths.

• Otherwise, it will either raise an unsupported font error, or trigger display of installation instructions for that specific font.

The Fontist::Font interface exposes an interface to list all supported fonts.

This might be useful if want to know the name of the font or the available styles. You can do that by using:

The return values are model objects, so you can easily access their properties and perform operations on them.

The Fontist::Formula.find interface allows you to find any of the registered formula. This interface takes a font name as an argument and it looks through each of the registered formula that offers this font installation. Usages:

This method will search and return a Fontist formula for the provided keyword which allows for further processing, such as license checks or proceeding with installation of the font in your system.

Normally, each font name can be associated with multiple styles or collection, for example the Calibri font might contains a regular, bold or italic styles fonts and if you want a interface that can return the complete list then this is your friend.

You can use it as following:

The Fontist::Formula interface exposes an interface to list all registered font formula. This might be useful if want to know the name of the formula or what type fonts can be installed using that formula. Usages:

The return values are model objects, so you can easily access their properties and perform operations on them.

Fontist can be switched to use the preferred family names. This format was used prior to v1.10.

Fontist lets you find font locations from a defined manifest Hash in the following format:

Calling the following code returns a nested Hash with font paths and names. Font name is useful to choose a specific font in a font collection file (TTC).

Fontist lets you not only to obtain font locations but also to install fonts from the manifest:

It will install fonts and return their locations:

Both commands support a YAML file as an input with a from_file method. For example, if there is a manifest.yml file containing:

Then the following calls would return font names and paths, as from the from_hash method (see Install and Locations).

macOS since 10.12 (Sierra) provides a "supplementary fonts" framework (shared with iOS) for dynamically downloading and installing a wide range of licensed fonts on demand.

These macOS-specific supplementary fonts can be installed through Fontist formulas.

A typical use for installing macOS add-on fonts is to allow CI jobs on macOS environments to use these specially-licensed fonts not available on other platforms.

This blog post describes how this works:

• Fontist blog: Installing macOS-specific add-on fonts

For example, the "Canela" font is a commercial font that comes free with macOS.

Run this command to install Canela on macOS.

The full list of available fonts on various macOS versions can be found on the Apple Support site:

The macOS supplementary font catalog for each macOS version is bound to a specific framework version. Different framework versions contain different sets of fonts, and often different versions of the same fonts.

A macOS system is only able to download fonts from the catalog version corresponding to its framework version, and Fontist respects this limitation when installing these fonts.

In Fontist Formulas, each supplementary font is backed by a formula specifying the font framework version it belongs to, using the catalog_version attribute. As a result, the same supplementary font will use different formulas for different macOS versions.

When you install a macOS add-on font, Fontist automatically detects your macOS version and installs the appropriate font version:

This ensures you always get the font version compatible with your system.

Fontist controls the macOS supplementary font framework versioning via platform tags on formulas.

The platform tag for macOS supplementary fonts follows the pattern: * macos-fontX: where X is the catalog version number (e.g. 3 to 8)

When installing fonts, Fontist checks version compatibility:

If you encounter version compatibility issues, ensure you’re running a compatible macOS version for the requested font.

Fontist provides comprehensive Windows platform support, allowing installation and management of fonts on Windows 7 and later.

Windows font management differs from Unix systems in several key ways:

• Uses backslash (\) as the path separator

• Stores fonts in registry-based and directory-based locations

• Requires different handling for file locking and permissions

• Uses case-insensitive (but case-preserving) file system

Fontist supports the following Windows font locations:

System fonts

• C:\Windows\Fonts - Primary system font directory

• Requires administrator privileges for installation

User fonts

• %LOCALAPPDATA%\Microsoft\Windows\Fonts - Per-user font directory (Windows 10+)

• No administrator privileges required

• Fontist creates a fontist subdirectory to avoid cluttering the main directory

Fontist library

• %USERPROFILE%\.fontist\fonts - Fontist-managed fonts

• Default installation location

• No administrator privileges required

File locking

Windows uses stricter file locking than Unix systems. Fontist handles this with automatic retry logic when encountering locked files during cleanup operations.

Path handling

Fontist automatically handles Windows path separators and drive letters. Font paths are returned in Windows-native format (e.g., C:\Users\user\.fontist\fonts\font.ttf).

Registry integration

While Windows historically used registry-based font registration, modern Windows (10+) supports directory-based fonts. Fontist uses directory-based installation for maximum compatibility and ease of management.

Administrator privileges

Installation to the system location requires administrator privileges. Use the user or fontist locations for installations without administrative access.

Fontist formulas can be easily hand-crafted in YAML. However, the auto-generation method is recommended for data accuracy and convenience.

A formula could be generated from a fonts archive.

The fontist create-formula command allows detecting all font files from a font archive in a multitude of formats (those supported by Excavate, including zip, 7z, gzip, tar, cab, exe).

The fontist create-formula command supports archives located at remote URLs or local file paths.

For file paths, specify the file path as argument:

For URLs, simply specify the URL as the argument:

To test out the created formula, one may copy the formula into the user’s private formula repository location.

The create-formula command supports several options to customize formula generation:

--name

Specify a custom formula name instead of auto-detecting from fonts.

fontist create-formula https://example.com/fonts.zip --name "My Custom Fonts"

--subdir

Extract fonts only from a specific subdirectory within the archive. Uses fnmatch patterns.

fontist create-formula https://example.com/fonts.zip --subdir "fonts/otf"

--file-pattern

Filter font files by pattern. Uses fnmatch patterns.

fontist create-formula https://example.com/fonts.zip --file-pattern "*.otf"

--name-prefix

Add a prefix to all font family names in the generated formula. This is useful for distinguishing compatibility or replacement fonts from original proprietary fonts.

fontist create-formula https://dl.winehq.org/wine/source/10.x/wine-10.18.tar.xz \
  --subdir fonts \
  --file-pattern '*.ttf' \
  --name-prefix 'Wine '

This will generate a formula where all fonts have names prefixed with "Wine ", making it clear these are Wine compatibility fonts rather than the original Microsoft fonts.

--mirror

Specify mirror URLs for the font archive (can be used multiple times).

fontist create-formula https://example.com/fonts.zip \
  --mirror https://mirror1.example.com/fonts.zip \
  --mirror https://mirror2.example.com/fonts.zip

Fontist imports font formulas from various external sources, and tracks the origin and metadata of these imported formulas using a polymorphic import_source attribute.

The import_source attribute contains metadata about where and when a font formula was imported from, enabling formula versioning, update detection, platform compatibility checks, and audit trails.

Fontist supports multiple import source types, each with specific metadata:

macOS Supplementary Fonts

Uses multi-dimensional versioning with framework version, catalog posted date, and asset build ID.

Google Fonts

Tracks commit ID from the Google Fonts repository, API version, last modified date, and family ID.

SIL International Fonts

Records the version string and release date.

macOS supplementary fonts use multi-dimensional versioning:

Framework Version

Font7, Font8 - determines schema and parser

Catalog PostedDate

Version of catalog within framework

Asset Build ID

Individual package identifier

Framework-specific metadata (min/max macOS versions, parser classes) is stored in lib/fontist/macos_framework_metadata.rb.

Formulas with import sources use differentiation keys for filename generation:

The filename format depends on the import source type:

• macOS: {normalized_name}_{asset_id}.yml (e.g., al_bayan_10m1360.yml)

• Google Fonts: {normalized_name}.yml (e.g., roboto.yml) - simple, no versioning

• SIL: {normalized_name}_{version}.yml (e.g., charis_sil_6.200.yml)

This approach enables:

• Multiple versions of the same font coexist (macOS, SIL)

• Clear tracking of font updates (all sources)

• Automatic update detection when catalogs refresh (all sources)

• Platform-specific version selection (macOS)

• Simple, consistent filenames for live services (Google Fonts)

Google Fonts provides the largest collection of freely and openly licensed fonts, including many that are widely used in web design and digital publishing.

Fontist’s formula library includes support for all fonts provided through Google Fonts, and maintains Fontist formulas for all such fonts.

Fontist supports importing fonts from Google Fonts in multiple formats:

TTF

(TrueType Font) Standard font files

VF

(Variable Fonts) Fonts with adjustable design axes (weight, width, slant, etc.)

WOFF2

(Web Open Font Format 2) Optimized web fonts

Each Fontist Google Fonts formula is automatically generated and updated using two data sources:

• The Google Fonts GitHub repository provides structured metadata and font file sources (OTF/TTF and Variable Fonts).

• The Google Fonts Developer API provides Google Fonts CDN URLs, static versions of Variable Fonts and WOFF2 web font files.

Google Fonts API provides separate endpoints for TTF fonts, Variable Fonts, and WOFF2 web fonts. Fontist integrates data from these endpoints and merges them into a unified database.

The Google Fonts importer uses a layered, object-oriented architecture:

The Google Fonts importer uses an ultra-simple architecture with FontDatabase as the single entry point and four equal data sources:

Models (lib/fontist/import/google/models/)

Data structures for font information

FontFamily

Unified font data (API + Github metadata)

Axis

Variable font axes information

FontVariant

Individual font file data

Data Sources (lib/fontist/import/google/data_sources/)

Four equal sources providing different information

Ttf

Fetches TTF URLs from Google Fonts API

Vf

Fetches variable font URLs + axes from Google Fonts API

Woff2

Fetches WOFF2 URLs from Google Fonts API

Github

Reads metadata from local google/fonts repository

Database (lib/fontist/import/google/font_database.rb)

Single entry point for all operations

• Merges data from all 4 sources

• Query methods: all_fonts, font_by_name, variable_fonts_only

• Formula generation: to_formula(name), save_formulas(dir)

API (lib/fontist/import/google/api.rb)

Optional convenience facade for API-only operations

The Fontist Google Fonts can be used via Ruby library to query font data or generate formulas:

For detailed usage examples, see Google Fonts Multi-Format Usage Guide.

Prerequisites:

1. Local git checkout of the google/fonts repository.

2. Google Fonts Developer API key (set using export GOOGLE_FONTS_API_KEY=your_api_key).

To update Google Fonts formulas from a local checkout of the google/fonts repository:

To import a single font for testing:

Fontist uses a GHA workflow to check for updated fonts on Google Fonts daily.

New, updated, or removed fonts are automatically committed to the Fontist formula repository.

During formula imports, Fontist is required to download font archives from various external sources for analysis to create accurate formulas.

To optimize performance and avoid redundant downloads, Fontist implements an import cache for storing downloaded font files at:

• Import cache (~/.fontist/import_cache): Font archives downloaded during formula building

Cache management is managed through the fontist cache command.

Use --verbose to see detailed cache operations:

OUTPUT includes:

• Import cache location

• Download URLs and cache status

• Extraction directory locations

• Cache cleanup notifications

All import commands (macos, google, sil) provide a unified, professional interface with colored output and progress tracking.

Enable --verbose to see detailed import progress:

Verbose output includes:

• Paint-colored headers with Unicode box characters

• Import cache location

• Download URLs and cache status

• Extraction directory paths

• Real-time progress with percentages

• Per-font status indicators

• Detailed summary statistics