TeX Live updmap and fmtutil, -sys vs. -user

On this page: best practice - use cases - system mode vs. user mode - switching back to system mode.

This page is about usage and best practices for the updmap and fmtutil scripts in TeX Live. updmap manages font map files (used by pdftex, dvips, dvipdfmx, pxdvi) in TeX Live, and fmtutil manages formats for TeX Live.

These scripts work in one of two modes: user or sys(tem) mode. If no mode is specified, a warning is printed. (This is as of TeX Live 2017, when the -user variants were created; before that, the script name without a suffix was the user variant.)

• System mode is selected by invoking updmap-sys resp. fmtutil-sys, or giving the command line option -sys.
• User mode is selected by invoking updmap-user resp. fmtutil-user, or giving the command line option -user.

Before going into details about the differences, some best practices follow.

Best practice and common cases

The best recommendation is the simplest: just use system mode (updmap-sys, fmtutil-sys)!

Running a program a single time in user mode switches permanently: the result is that future updates to the system will be invisible, hidden by the user files. So, think twice and understand what you're doing before running anything in user mode.

Following are some typical use cases.

Use case 1: single-user computer - add fonts

Probably the most common case. Here is the recommendation:

1. Put the fonts into TEXMFLOCAL (with the full subdirectory structure, following the TDS); by default, this is /usr/local/texlive/texmf-local.
2. Add the font map to the file TEXMFLOCAL/web2c/updmap.cfg, creating it if necessary.
3. run (once) updmap-sys (no options needed).

Advantages: Upgrades to new TeX Live releases in future years will pick up the fonts automatically. No future manual intervention is needed.

Use case 2: multi-user computer - add system-wide fonts

A common need in a department or company with organization-specific fonts, which all users should have access to:

Follow use case 1. That is all!

Use case 3: multi-user computer - private user fonts

This is the only case where user mode is required, and thus TEXMFHOME is used instead of TEXMFLOCAL:

1. Put fonts into TEXMFHOME, following the TDS
2. add the font map lines to TEXMFHOME/web2c/updmap.cfg, creating it if necessary.
3. Run updmap-user once.

Important: after this, changes in the font setup of the system installation will not be seen until updmap-user is run again. Thus, you should run updmap-user whenever you think there might be changes in the set of installed fonts. There is no harm in running it extra times, when it might not be needed, so it would be good to run it regularly from, e.g., cron.

Use case 4: adding formats

Creating new formats is a rare situation, but if it comes up, it can be handled analogously to case 1 above. That is, a new format is most probably intended for public use, so adding an entry to the file TEXMFLOCAL/web2c/fmtutil.cnf (creating it if necessary), then running fmtutil-sys suffices. Of course the TeX sources or other files needed by the format should also be installed in TEXMFLOCAL.

System mode vs. user mode

System and user mode have two main operational differences:

1. The location where files are generated: for user mode, this is TEXMFVAR; for system mode, TEXMFSYSVAR.
2. Configuration files used: in user mode, a few additional files are read; details are on updmap and fmtutil man pages (or, equivalently, the --help messages).

When a program is invoked in user mode, files are generated in TEXMFVAR (under the user's home directory). Since files in TEXMFVAR override the files in TEXMFSYSVAR (a system directory), they will take precedence over files in TEXMFSYSVAR forever after. Which in turn means that subsequent updates in the system-wide installation will not be visible to the user.

This has always been the primary confusion with fmtutil and updmap. It can be avoided by always using system mode, as recommended above. You can also go back to system mode fairly easily:

Switching back to system mode

If you accidentally or intentionally run a script in user mode, you may then later realize you want to go back to system mode (good decision).

Switching back to system mode involves removing files in TEXMFVAR, which by default is ~/.texliveYYYY/texmf-var, where YYYY is the TeX Live release. (Of course it's prudent, probably best, to move files to an area outside of any TeX directory, rather than literally removing them.)

• For updmap, the files in TEXMFVAR/fonts/map should be backed up and then removed.
• For fmtutil, the files in TEXMFVAR/web2c should be backed up and then removed.

In either case, those directories should contain only files which are automatically generated: but do yourself a favor, and check that no file you have yourself manually created is being removed.

We hope this page helps with this perennially painful topic. Please send suggestions and bug reports to the tex-live mailing list.