How to patch a font

July 30, 2022

Why?

I couldn’t find a complete, step-by-step guide on how to do this anywhere, so I figured I’d write one myself.

I spend a lot of time in the terminal, so I want the text I’m reading to be easy on the eyes, but also sharp and distinct enough that it’s easy to visually find any content I’m looking for.

I really like OSX’s Menlo font for reading text and editing code. I also like having icons in my editor, however since I work in a terminal, I need to “patch in” any icons I want to use into my font of choice.

Normally I’d just download a font that’s already been patched from a website like this, however I couldn’t find a patched version of Menlo anywhere.

In this article I’m going to walk through the steps to patch a built-in, OSX font (in this case Menlo), but these instructions apply to any TrueType font and TrueType Collection.

Assumptions

I use a MacBook Air running OSX so the following instructions are going to assume you’re also running OSX, however adapting these steps for Linux and Windows should be pretty trivial.

A script that does it all for you

I wrote a tool that handles all of the steps outlined below, and I highly recommend using it to follow along (or just use it instead of going through this article).

Instructions

1. Install the font patcher script.

curl https://raw.githubusercontent.com/ryanoasis/nerd-fonts/master/font-patcher \
  --create-dirs -o data/font-patcher \
  && chmod +x data/font-patcher

This Python script does most of the heavy lifting of patching in glyphs (i.e. icons) into the font of your choosing. It comes from Nerd Fonts, a repository that has a bunch of pre-patched fonts.

2. Install any glyphs

The Nerd Fonts repo has a directory of many glyph collections to choose from. Feel free to download one or many of the .ttf, .otf, and .sfd glyph files.

I recommend installing all of the glyphs as some glyphs depend on others.

The location that you download these files is very important. It needs to exatcly match the path in the Nerd Fonts repo inside the /glyphs directory (again, my script handles this). This is due to the glyph paths being hardcoded in the script we downloaded in Step 1.

Here are some commands you could run to download individual glyphs:

Pomicons

curl https://raw.githubusercontent.com/ryanoasis/nerd-fonts/master/src/glyphs/Pomicons.otf \
  --create-dirs -o data/glyphs/Pomicons.otf

Codicons

curl https://raw.githubusercontent.com/ryanoasis/nerd-fonts/master/src/glyphs/codicons/codicon.ttf \
  --create-dirs -o data/glyphs/codicons/codicon.ttf

3. Download or locate the font to be patched.

In my case, I already have Menlo installed on my machine at /System/Library/Fonts/Menlo.ttc.

4. Decompile the TrueType Collection

This step is only relevant if your font is a TrueType Collection (the font file extension is .ttc). If your font is a TrueType font (the font file has a .ttf extension) then skip to step 5.

4.1 Install FontTools

brew install fonttools

This will install a bundle of cli tools used for manipulating fonts. One of them that we’ll use is ttx.

4.2 Extract the TrueType XML files

ttx -y $TTF_INDEX -o $TTF_INDEX.ttx $FONT_PATH

Where:

These indicies map to individual TrueType fonts inside the TrueType Collection. There can be any number of TrueType fonts in a Collection, so we will run this command until we’ve extracted all of the fonts and stop when we get an error from ttx.

The resulting files will have a .ttx extension, and are essentially a special kind of XML file.

To actually import the TrueType fonts into Font Book (OSX’s font manager tool), we’ll need to convert these files to .ttf (in the next step).

In my case of extracting Menlo, I would run the following commands:

ttx -y 0 -o 0.ttx /System/Library/Fonts/Menlo.ttc
ttx -y 1 -o 1.ttx /System/Library/Fonts/Menlo.ttc
ttx -y 2 -o 2.ttx /System/Library/Fonts/Menlo.ttc
ttx -y 3 -o 3.ttx /System/Library/Fonts/Menlo.ttc

4.3 Compile the TrueType XML (.ttx) files to TrueType (.ttf) files

ttx -o $TTF_INDEX.ttf $TTF_INDEX.ttx

Similar to the previous step, we will run this command for each of the .ttx files we generated earlier.

For Menlo, I’d run the following:

ttx -o 0.ttf 0.ttx
ttx -o 1.ttf 1.ttx
ttx -o 2.ttf 2.ttx
ttx -o 3.ttf 3.ttx

5. Patch the TrueType font(s)

5.1 Install FontForge

brew install fontforge

This is another CLI tool that helps with editing TrueType Fonts/Collections.

5.2 Patch the TrueType font(s)

fontforge -script ./data/font-patcher $TTF_INDEX.ttf --complete --glyphdir ./data/glyphs/

Run this command on all .ttf files you want to patch. The --complete flag is included as I’m assuming you’ve downloaded all the glyphs provided by Nerd Fonts.

For patching all available glyphs into Menlo, I’d run the following commands:

fontforge -script ./data/font-patcher 0.ttf --complete --glyphdir ./data/glyphs/
fontforge -script ./data/font-patcher 1.ttf --complete --glyphdir ./data/glyphs/
fontforge -script ./data/font-patcher 2.ttf --complete --glyphdir ./data/glyphs/
fontforge -script ./data/font-patcher 3.ttf --complete --glyphdir ./data/glyphs/

6. Import the patched TrueType fonts with Font Book

After going through all of these steps, you should have some number of patched .ttf files.

In the case of Menlo, we can select the 4 patched TrueType fonts to import.

Depending on the font you’ve patched, you may have conflicts in the font’s “name” table.

Unless Font Book shows any errors (which will be marked with a red “X” symbol), feel free to select all fonts with warnings and click “Install Checked”.

Note: The reason why this happens is that the Nerd Font patching script creates duplicate Id’s in this “name” table. You can see what this looks like if you open up one of the .ttx files and search for “name”.

You should now have your imported font(s) available in Font Book.