Installing TeX fonts

Using a font that did not come with your TeX distribution requires several steps. But before we go into those details, consider these two alternatives:

This web page is about installing a font that has already been prepared for use with TeX (typically pdftex and/or dvips), not about the work of preparing the support files. That is a much more complicated job; see Philipp Lehman's Font Installation Guide and the Fontinst documentation for starters, if you want to delve into that.

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

If neither of the above alternatives suffice, then the first step is to determine in what directory the new font will live. You can't just choose 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 > MiKTeX Settings > Root
Some paths shown there have a Description such as Install, UserConfig, or UserData. Of these, UserConfig is an acceptable tree to install your new fonts, if you have no permission to create a new tree. However, it is better to use a tree without a description; these are true local trees.

You can add a new or an existing folder as the root of a new local tree to the list 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; for example, TFM files should be in /yourfolder/font/tfm. (More 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 (the perhaps unusual-looking) /usr/local/texlive/2008/../texmf-local, which is just another way of writing /usr/local/texlive/texmf-local.

If you are not using one of the above TeX distributions (MiKTeX, TeX Live, MacTeX), 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 “raw” font files without any structure, 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 available from CTAN 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 “filename database”.

MiKTeX
Navigate through the MiKTeX program:
Start > Programs > MiKTeX > MiKTeX Settings > General > Refresh Now (the file name database).
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 to be your personal home directory. This may or may not be needed, and may or may not cause trouble. Try omitting it if problems.)

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 next (and most complicated) step is to update various so-called “map” files with the information about your new font.

The commands below depend on your new font coming 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 Window/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 ...

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

If 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. It's best to leave off the .tfm extension. If you used the default texmf-local directory, on Unix-like systems and MacTeX, you can check for files in subdirectories of /usr/local/texlive/texmf-local/fonts/tfm/.

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 that frustrating result happens:

Good luck. Corrections to this web page are welcome, please email webmaster@tug.org.


$Date: 2010/02/26 23:55:52 $; TUG fonts page;
TUG home page; contact webmaster; (via Google)