This page covers how to obtain, install dependencies for, and run font-patcher directly. It explains the three supported invocation methods (FontForge script, standalone executable, Docker container), what prerequisites each requires, and how the output file is named and placed. For a complete reference of all command-line flags, see Patching Options. For batch processing of many fonts at once, see Batch Processing. For the Docker image in depth, see Docker Usage.
font-patcher is a Python script that uses FontForge's Python bindings to open a source font file, copy icon glyphs from bundled symbol fonts into it, rename the resulting font, and write the patched file to disk. It is the central tool in the Nerd Fonts pipeline.
Invocation flow:
Sources: font-patcher339-441 font-patcher441-527
| Requirement | Notes |
|---|---|
| Python 3 | Required to run the script |
| FontForge | Must be installed with Python bindings |
python-fontforge | The fontforge and psMat Python modules |
configparser | Standard library; if missing, install via pip install configparser |
src/glyphs/ directory | Symbol source fonts; included in FontPatcher.zip |
The script checks for fontforge and psMat at import time and exits with a descriptive message if either is missing:
It also attempts to load FontnameParser and FontnameTools from bin/scripts/name_parser/ and the Braille module from bin/scripts/braille/. Both are optional — if unavailable, those features are silently disabled.
| Platform | Command |
|---|---|
| Debian / Ubuntu | sudo apt install fontforge python3-fontforge |
| macOS (Homebrew) | brew install fontforge |
| Any (AppImage) | Download from the FontForge releases page |
Download the archive — do not download only the font-patcher script file. The script depends on companion files in src/glyphs/, bin/scripts/name_parser/, and bin/scripts/braille/.
Download the latest FontPatcher.zip archive from the project's releases page. After extracting, the directory should contain at minimum:
font-patcher
src/glyphs/ ← symbol font files
glyphnames.json
bin/scripts/name_parser/
bin/scripts/braille/
The glyphnames.json file is read at startup by fetch_glyphnames() to map codepoints to glyph names:
If the file is missing, a warning is logged and an empty dictionary is used — patching still proceeds.
Dependency diagram (code-level):
Sources: font-patcher26-54 font-patcher383-386 font-patcher328-337
fontforge -script (Recommended)fontforge -script font-patcher PATH_TO_FONT
This invokes FontForge as a Python interpreter with its bindings pre-loaded. It is the most reliable method because the fontforge module is guaranteed to be in scope.
Example with additional flags:
fontforge -script font-patcher MyFont.ttf --complete --mono -out /tmp/patched
./font-patcher PATH_TO_FONT
This works when the system's python3 executable can locate the fontforge module directly. It may fail if FontForge's Python bindings are not on the default PYTHONPATH.
When using the AppImage distribution of FontForge, all paths must be absolute and an explicit output directory is required:
./FontForge.AppImage -script $PWD/font-patcher $PWD/MyFont.ttf --complete -out /tmp/patched
The $PWD shorthand satisfies the absolute path requirement without manual typing.
The nerdfonts/patcher Docker image bundles FontForge and the patcher in a pre-configured Alpine Linux environment.
docker run --rm \
-v /path/to/fonts:/in:Z \
-v /path/for/output:/out:Z \
nerdfonts/patcher [OPTIONS]
The container reads all font files from the /in volume and writes patched fonts to /out. By default it runs multiple patch jobs in parallel. To control parallelism, set the PN environment variable:
| Command | Effect |
|---|---|
(no PN) | Default parallel jobs |
-e "PN=1" | Single process (slower but simpler output) |
-e "PN=10" | Up to 10 parallel jobs |
To get an interactive shell inside the container for full control:
docker run -it \
-v /path/to/fonts:/in:Z \
--entrypoint=/bin/sh \
nerdfonts/patcher
Then inside the container:
cd /in
fontforge --script ../nerd/font-patcher [OPTIONS] your_font.ttf
The Dockerfile builds FontForge from source on Alpine Linux and installs GNU parallel for multi-job support:
For more on the Docker image build process, see Docker Usage.
font-patcher takes exactly one positional argument — the path to the font file to patch:
font-patcher [OPTIONS] font
Supported input formats include .ttf, .otf, and .sfd files. Font collection (.ttc) files are handled internally by TableHEADWriter:
Output directory: Defaults to the current working directory. Override with --outputdir / -out.
Output filename: Derived from the patched font's SFNT name table entries after renaming. The create_filename() function reads the Preferred Family and Preferred Styles fields (falling back to Family and SubFamily):
For a single-font output the filename is <PreferredFamily>-<PreferredStyles> with spaces removed. For a font collection (.ttc) output, only the family name is used.
Output format: Defaults to the same extension as the input font (.ttf or .otf). Override with --extension / -ext.
Naming example:
Input:
Inconsolata-Regular.ttfOutput:InconsolataLGCNerdFont-Regular.ttf(exact name depends on rename logic and flags used)
[!NOTE] The output font's family name is set to the original family name (after CamelCasing and space removal) with
Nerd Fontappended. For example,iosevka termbecomesIosevkaTerm Nerd Font.
At runtime, font_patcher.patch() checks that the glyph directory exists before processing:
If --glyphdir is not specified, it defaults to src/glyphs/ relative to the script location. The patcher opens each required symbol font file from this directory as a FontForge font object, scales it to match the source font's em units, and copies glyphs from it.
Runtime data flow:
Sources: font-patcher355-527
After FontForge generates the output file, font_patcher.generate() uses TableHEADWriter to correct binary-level fields that FontForge does not preserve correctly: xAvgCharWidth, the ppem_to_int flag, lowestRecPPEM, and the full-file checksum adjustment:
If --postprocess SCRIPT is specified, font_patcher.generate() calls the script with the output file path as its sole argument after writing the font:
This can be used for any custom transformation, such as subsetting, compression, or renaming.
# Recommended: via fontforge -script
fontforge -script font-patcher MyFont.ttf --complete
# With explicit output directory
fontforge -script font-patcher MyFont.ttf --complete -out ~/patched/
# Monospaced variant
fontforge -script font-patcher MyFont.ttf --complete --mono
# Add only specific symbol sets
fontforge -script font-patcher MyFont.ttf --fontawesome --octicons
# AppImage (all paths must be absolute)
./FontForge.AppImage -script $PWD/font-patcher $PWD/MyFont.ttf --complete -out /tmp
# Docker (default parallelism)
docker run --rm -v ~/myfont/patchme:/in:Z -v ~/myfont/patched:/out:Z nerdfonts/patcher --complete
# Docker (single process)
docker run --rm -v ~/myfont/patchme:/in:Z -v ~/myfont/patched:/out:Z -e "PN=1" nerdfonts/patcher
Sources: readme.md428-468 readme.md563-578
For the full list of symbol set flags and expert options, see Patching Options.
For the font naming system and how FontnameParser constructs output names, see Font Naming System.
For batch-patching all fonts in the repository at once, see Batch Processing.
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.