Installing TeX fonts

This web page is about installing a font that has already been prepared for use with TeX (typically pdftex and/or dvips). Using a font that did not come with your TeX distribution requires several steps. Before we go into those details, consider these two alternatives:

Also, this web page doesn't try to cover everything (it's already plenty complicated). Limitations:

The TUG fonts page has references to fonts commonly used with TeX, and general information on TeX font usage.

1. Destination texmf-local: your local TeX tree

The first step is to determine in what directory the new font will live. You can't choose just any directory, it has to be part of the TeX hierarchy. The best choice is your “local texmf” tree, which you can determine as follows:

MiKTeX
Navigate through the MiKTeX program:
Start > Programs > MiKTeX > Maintenance > Roots
(or MiKTeX Settings, in older versions). Some paths shown there have a Description such as Install, UserConfig, or UserData. A tree labeled UserConfig (but not any of the others) is an acceptable target for your new fonts, if you have no permission to create a new tree. However, it is better to use a tree without a description, as follows:

You can create a new local tree by clicking on Add. The folder must not contain files at its root level or MiKTeX will reject it. Files in the folder must be in subfolders similar to the subfolders in the Install root. (MiKTeX info.)

TeX Live and MacTeX
From a system terminal (aka command prompt, shell window) enter the command kpsewhich --var-value TEXMFLOCAL to see the directory name. The default on Unix is /usr/local/texlive/texmf-local.

If you are not using one of the above TeX distributions, you'll need to consult other documentation.

2. The TeX Directory Structure: unpacking your archive

After determining your local tree for installation (see previous section), the next step is to copy the new files into subdirectories of that tree. Hopefully, your new font came as a zip or other archive file that is already arranged according to the standard TeX Directory Structure (TDS). If this is the case, you can simply unpack it at the top level of your chosen tree.

You can check by inspecting your archive (with unzip -l yourfile.zip, for example). If it has subdirectories such as fonts/ and tex/, it's most likely arranged according to the TDS.

If you're getting a flat list of font files without any directories, then you have to move the files yourself into the appropriate subdirectory. Please read the TeX FAQ entry and TDS document (html, pdf).

Warning: some unzip programs take it upon themselves to create their own top-level directory, usually named after the zip file. You must avoid these programs. The plain unzip program, version 5.52 or thereabouts, which is the usual unzip on MacOSX and other Unix-like systems, works fine; you can run unzip --version to check what you've got. The UnZip home page lists working unzip binaries for many systems.

3. The TeX filename database

After getting your new files into their proper location (see previous sections), you must update the so-called “TeX filename database”.

MiKTeX
Navigate through the MiKTeX program:
Start > Programs > MiKTeX > Maintenance > Settings > General > Refresh FNDB
(In older versions of MiKTeX, it may be under a menu called MiKTeX Options instead of Maintenance.) There may also be a Maintenance(Admin) entry if you have administrative privileges; if so, that is usually the better choice. Or, if you prefer a DOS command line: initexmf --update-fndb.

MacTeX
Run the command sudo -H mktexlsr. (The -H sets HOME for the sudo environment.)

TeX Live
Run the command mktexlsr (the command texhash is a synonym). On Unix-like systems, run sudo -H mktexlsr if you installed your system as root (not recommended).

4. Font map files: telling TeX about the new font

After recording the new files (see the previous sections), the last (and most complicated) step is to update various so-called “map” files with the information about your new font.

The commands below assume your new font comes with a map file. If you have no map file, then it has to be created, and that is not an easy job. See the references at the end.

The commands below use newfont.map for the name of this map file. There are no standard conventions for the name, so it can't be guessed; check your original archive for the name used.

MiKTeX
First, edit the map configuration file updmap.cfg as follows. In a DOS/Command Prompt window, run:
initexmf --edit-config-file updmap
You'll want to edit this in a text editor such as Notepad.

Second, add this one line to updmap.cfg and save it:
Map newfont.map

Third, back at the DOS prompt, run:
initexmf --mkmaps
(Ignore any error messages.)

TeX Live and MacTeX
Run the command:
updmap-sys --enable Map=newfont.map

On MacOSX, this is typically done as system administrator, so:
sudo -H updmap-sys ...

Again, this page is about installing fonts in a system-wide directory. If you need or want to use a personal directory such as TEXMFHOME, please see the separate page about installing fonts in a personal directory.

After doing this, you should remake the filename database again, as explained above; this is not always necessary, depending on your setup, but should never hurt.

5. Testing and debugging

Once all the above seems to have gone ok, to test if the new font is properly recognized, you can use the standard testfont.tex file, like this (prompts also shown):

$ tex testfont  # or pdftex testfont
...
Name of the font to test = tfmname
...
*\table
*\bye

It is imperative to enter the exact name of a .tfm file that was installed, not a system font name or a PostScript font name or anything else. The only thing TeX will recognize is the .tfm filename. Furthermore, leave off the .tfm extension.

The result of the above run should be a DVI or PDF file, according to whichever tex you invoked, showing the characters in that TFM.

If there are problems, typically dvips or pdftex will try to make bitmaps from the font, perhaps with “missing font” messages. If you get that frustrating result:

Good luck. If you have technical questions or problems with installing fonts, please try writing texhax@tug.org. For corrections to this web page, contact the TUG webmaster (link below).


$Date: 2014/07/08 15:38:28 $; TUG fonts page;
TUG home page; contact webmaster; (via Google)