How to fix LuaTeX/LuaLaTeX font cache not updating and documents compiling extremely slowly after installing large fonts

!README.md

Fix for LuaLaTeX hanging after installing large fonts

TL;DR:

In a terminal, do:

luaotfload-tool -ufvvv

and let it run until it hangs. Use CTRL+C to abort, then do:

echo "iosevka.ttc" >> "$(kpsewhich -expand-var '${TEXMFHOME}/tex/luatex/luaotfload/luaotfload-blacklist.cnf')"

Replace iosevka.ttc with the filename of the problematic font. Then try the first command again.

Notes

• In my experience, the culprit is likely a large TrueType Collection (TTC), such as the popular Iosevka typeface.
• Using kpsewhich to expand the TEXMFHOME path is safer than relying on shell expansion or default paths.
• As far as I know, it shouldn't be necessary to run mktexlsr after the commands above, even with TeX Live.

The explanation

Per the luaotfload package documentation:

8.4 Blacklisting Fonts

Some fonts are problematic in general, or just in LuaTeX. If you find that compiling your document takes far too long or eats away all your system’s memory, you can track down the culprit by running luaotfload-tool -v to increase verbosity. Take a note of the filename of the font that database creation fails with and append it to the file luaotfload-blacklist.cnf.

A blacklist file is a list of font filenames, one per line. Specifying the full path to where the file is located is optional, the plain filename should suffice. File extensions (.otf, .ttf, etc.) may be omitted. Anything after a percent (%) character until the end of the line is ignored, so use this to add comments. Place this file to some location where the kpse library can find it, e.g. texmf-local/tex/luatex/luaotfload if you are running TeX Live¹ or just leave it in the working directory of your document. luaotfload reads all files named luaotfload-blacklist.cnf it finds, so the fonts in ./luaotfload-blacklist.cnf extend the global blacklist.

Furthermore, a filename prepended with a dash character (-) is removed from the blacklist, causing it to be temporarily whitelisted without modifying the global file. An example with explicit paths:

/Library/Fonts/GillSans.ttc
-/Library/Fonts/Optima.ttc

Footnotes

1. You may have to run mktexlsr if you created a new file in your texmf tree. ↩