Eliminating font cache problems

Tutorial
by Rainer Erich Scheichelbauer
en fr zh

3 August 2022 Published on 24 May 2013

Re-installing a font in Font Book can create font cache troubles. Here is how to avoid it.

If you want to test your font in a real-life situation, and you are thinking about Adobe apps, well, then you can use the Adobe Fonts folder, and avoid cache problems from the start. Congratulations: You do not need to read any further, you are done!

Testing in non-Adobe apps

But let us assume you decided to test your font in an application like TextEdit or Word. So, you install it in the system by either opening it in Apple’s Font Book app, or by using a third-party font manager, or by simply dragging the font file into ~/Library/Fonts/.

Well, you shouldn’t.

Why not? Because installing a font with the same name as a previously installed one can seriously mess up your font caches. Caches are collections of previously calculated data. They can speed up your computer because it does not have to reprocess the original information every time. Likewise, font caches allow your Mac to speed up the use of installed fonts because all the stuff your Mac had to calculate to make your font appear on the screen, has already been done.

But, of course, if the original font has changed, and the font cache does not know about it, then the data stored in it is outdated and most likely wrong. Typical symptoms include:

  • The font menu does not show your font anymore
  • Glyphs do not appear at all
  • Changes you made in the font do not appear on the screen
  • Glyphs appear garbled and messed up on screen
  • You type one letter, but a different one appears
  • Paragraphs do not reflow properly
  • Your font does not print, or prints wrong or garbled letters

Or any other font weirdness, really.

Cleaning caches

If this happens to you, delete the font from Font Book or whatever third-party utility you use. Important: Don’t just deactivate it, REMOVE IT. Afterwards, you have two options:

First line of defence: restart with Shift

Restart your Mac while holding down your Shift key until it says ‘Safe Mode’ on your screen. Starting with Shift should cause your Mac to delete and rebuild its caches, amongst which the font cache. Once your login screen comes up, log in to your user, and restart again, this time without the Shift key.

Important: restarting twice is essential, because the first restart (with Shift) deletes the root of all evil, the font cache. But because it is starting in Safe Mode, some kernel extensions are not loaded, and your Mac may not appear as performant and snappy as usual. So, the second restart (without Shift) boots your Mac normally again.

Your Mac may be a little busy for a while, so you may see more HD and CPU action for a few minutes. That is OK, because it is rebuilding its caches.

Make Apple Type Server clean its database

Should this not help, or if you simply want to avoid restarting twice, open up your Terminal.app (you can find it in /Applications/Utilities/) and type (or copy and paste) the following commands. If you type them, each line must be finished by pressing the Return key; if you paste them, you may need to press Return to confirm the entry of the third line. The first code line will prompt you for your password. Attention, you will not see ‘passphrase bullets’ (•••) indicating the password length. Type it anyway and confirm by pressing the Return key:

sudo atsutil databases -remove
atsutil server -shutdown
atsutil server -ping

And now, restart your Mac. No, really, open the Apple menu in the top left corner and choose Restart. Don’t think you can get away without a restart, otherwise the trouble will reappear. And you really do not want that, do you? OK, restart your Mac.

Cleaning caches with an AppleScript

Since you are on a Mac, you can put these exact commands in an AppleScript, and make it conveniently available in the Script menu. Thus, you do not need to remember the Terminal voodoo or go looking for this blogpost again.

OK, let’s do this. In Finder, Choose Go > Utilities (Cmd-Shift-U) and double click the app called Script Editor:

Make a new script with File > New (Cmd-N), and copy and paste this into the new window:

try
    do shell script "sudo atsutil databases -remove" with administrator privileges
on error errMsg number errNum
    display dialog "Font cache error " & errNum & ": " & errMsg
end try
do shell script "atsutil server -shutdown"
do shell script "atsutil server -ping"
set buttonAnswer to text of button returned of (display dialog "It is strongly recommended that you restart your Mac, or at least log out and back in again." with title "Font caches cleaned" with icon caution buttons {"Restart", "Log out", "Later"} default button 3)
if buttonAnswer is "Log out" then
    tell application "System Events" to log out
else if buttonAnswer is "Restart" then
    tell application "System Events" to restart
end if

Click on the button with the hammer icon (Compile the Script) to verify the code. The code should now be syntax-coloured:

Save the script in your User Scripts folder. To do that, choose File > Move To…, and in the dialog that follows, press Cmd-Shift-G to bring up the Go to the Folder dialog. Here, you copy and paste this line:

~/Library/Scripts/

When you do that, it will probably look something like this:

Press Go, and the Move To dialog shows the User Scripts folder, which is where we want to move our script. So you can safely press Move now.

Don’t forget to rename it to something that makes sense. Choose File > Rename… and call it Clean Font Caches.scpt or something like that. When you are done with that, turn on your Script menu, so you can easily access your AppleScript whenever you need it. To do that, access the preferences via Script Editor > Preferences (Cmd-comma), go to the General tab of the Preferences window, and make sure the checkbox next to Show Script menu in menu bar is on:

In the top right corner of your screen, your Mac displays a range of menu bar items. One of them is the Script menu. It allows you to run AppleScripts saved in special folders, one of them being ~/Library/Scripts/. So, when you click on it, you should see the AppleScript we just saved there:

Now you can:

  1. remove the font from your system, e.g., in Font Book,
  2. run the script (via the AppleScript menu) to clean your font caches,
  3. restart your Mac (the script gives you an option to do that right away),
  4. install the new version of your font, and start using it without issues.

Avoiding cache problems

There are a few simple ways to actually avoid the cache problems in the first place.

  1. Firstly, as mentioned at the beginning, test your fonts in Adobe apps. They have a special Fonts folder, fonts saved into these folders are active in Adobe apps right away, and, most importantly, they are not cached.

  2. Secondly, if you really have to test your font in the system, then change the Family Name every time you install the font. You can extend the name by a number or a letter. Since the font caches are linked to the font name, a new installation of the font with a different name will not conflict with a previous installation. Only downside: after a few iterations, you will clutter your font menu to a point where it becomes difficult to handle.

  3. Thirdly, and probably best of all, use the little TextPreview tool we created for just that purpose. It can watch a folder for new fonts added to it, and make them available in the app without installing them. Find the app on our Tools page.

Workaround Export with unique file names

Nico Hagenburger found out that the macOS font cache depends on the file name of the font file. So if you make sure that the OTF you export has a different file name every time you export, and you delete all previous versions, you should be fine. Nico was so nice to write a Python script called Export and Install that does exactly that. Click the link to open the script in Plugin Manager.

If you want to know more, Nico wrote a Medium article about it: Install Fonts Without Caching Issues on MacOS.


SAMPLE FONT: ALENA BY ROLAND STIEGER
Update 2013-07-04: clarified where to delete the font.
Update 2014-06-16: removed the superfluous user-specific cache-cleaning, the sudo line removes all caches.
Update 2016-01-02: added link to Adobe Fonts Folder tutorial.
Update 2016-02-19: updated screenshots for Glyphs 2.
Update 2017-06-04: partial rewrite for better clarity, new screenshots, added TextPreview.
Update 2018-06-06: added ‘Workaround: Export with Changing File Names’. (Thx Nico!)
Update 2019-02-25: added ‘Restart with Shift’.
Update 2020-08-23: added link to Nico Hagenburger’s Medium article.
Update 2022-08-03: updated title and link, related articles, minor (re)formatting.