FMTUTIL(1) User Commands FMTUTIL(1)
NAME
fmtutil - manage TeX formats and Metafont bases, per-user
fmtutil-sys - manage TeX formats and Metafont bases, system-wide
mktexfmt - create a TeX format or Metafont base
SYNOPSIS
fmtutil [-user|-sys] [OPTION] ... [COMMAND]
fmtutil-sys [OPTION] ... [COMMAND]
fmtutil-user [OPTION] ... [COMMAND]
mktexfmt FORMAT.fmt|BASE.base|FMTNAME
DESCRIPTION
fmtutil version r68962 (2023-11-25 00:01:43 +0100)
Rebuild and manage TeX fmts and Metafont bases, collectively called
"formats" here. (MetaPost no longer uses the past-equivalent "mems".)
If not operating in mktexfmt mode, exactly one command must be given,
filename suffixes should generally not be specified, no non-option argu-
ments are allowed, and multiple formats can be generated.
If the command name ends in mktexfmt, only one format can be created.
The only options supported are --help and --version, and the command
line must be either a format name, with extension, or a plain name that
is passed as the argument to --byfmt (see below). The full name of the
generated file (if any) is written to stdout, and nothing else. The
system directories are used if they are writable, else the user directo-
ries.
By default, the return status is zero if all formats requested are suc-
cessfully built, else nonzero.
OPTIONS
--sys use TEXMFSYS{VAR,CONFIG}
--user use TEXMF{VAR,CONFIG}
--cnffile FILE
read FILE instead of fmtutil.cnf (can be given multiple times, in
which case all the files are used)
--dry-run, -n
don't actually build formts
--fmtdir DIR
write formats under DIR instead of TEXMF[SYS]VAR
--no-engine-subdir
don't use engine-specific subdir of the fmtdir
--no-error-if-no-format
exit successfully if no format is selected
--no-error-if-no-engine=ENGINE1,ENGINE2,...
exit successfully even if a required ENGINE
is missing, if it is included in the list.
--no-strict
exit successfully even if a format fails to build
--nohash
don't update ls-R files
--recorder
pass the -recorder option and save .fls files
--refresh
recreate only existing format files
--status-file FILE
append status information about built formats to FILE
--quiet
be silent
--catcfg
(does nothing, exists for compatibility)
--dolinks
(does nothing, exists for compatibility)
--force
(does nothing, exists for compatibility)
--test (does nothing, exists for compatibility)
Commands (exactly one must be specified):
--all recreate all format files
--missing
create all missing format files
--byengine ENGINE
(re)create formats built with ENGINE
--byfmt FORMAT
(re)create format FORMAT
--byhyphen HYPHENFILE
(re)create formats that depend on HYPHENFILE
--enablefmt
FORMAT[/ENGINE] enable FORMAT, as built with ENGINE
--disablefmt FORMAT[/ENGINE]
disable FORMAT, as built with ENGINE If multiple formats have the
same name and
different engines, /ENGINE specifier is required.
--listcfg
list (enabled and disabled) configurations, filtered to available
formats
--showhyphen FORMAT
print name of hyphen file for FORMAT
--version
show version information and exit
--help show this message and exit
ENVIRONMENT
Explanation of trees and files normally used:
If --cnffile is specified on the command line (possibly multiple
times), its value(s) are used. Otherwise, fmtutil reads all the
fmtutil.cnf files found by running "kpsewhich -all fmtutil.cnf",
in the order returned by kpsewhich. Files specified via --cnf-
file are first tried to be loaded directly, and if not found and
the file names don't contain directory parts, are searched via
kpsewhich.
In any case, if multiple fmtutil.cnf files are found, all the
format definitions found in all the fmtutil.cnf files are merged.
Thus, if fmtutil.cnf files are present in all trees, and the de-
fault layout is used as shipped with TeX Live, the following
files are read, in the given order.
For fmtutil-sys:
TEXMFSYSCONFIG $TEXLIVE/YYYY/texmf-config/web2c/fmtutil.cnf
TEXMFSYSVAR $TEXLIVE/YYYY/texmf-var/web2c/fmtutil.cnf
TEXMFLOCAL $TEXLIVE/texmf-local/web2c/fmtutil.cnf
TEXMFDIST $TEXLIVE/YYYY/texmf-dist/web2c/fmtutil.cnf
For fmtutil-user:
TEXMFCONFIG $HOME/.texliveYYYY/texmf-config/web2c/fmtutil.cnf
TEXMFVAR $HOME/.texliveYYYY/texmf-var/web2c/fmtutil.cnf
TEXMFHOME $HOME/texmf/web2c/fmtutil.cnf
TEXMFSYSCONFIG $TEXLIVE/YYYY/texmf-config/web2c/fmtutil.cnf
TEXMFSYSVAR $TEXLIVE/YYYY/texmf-var/web2c/fmtutil.cnf
TEXMFLOCAL $TEXLIVE/texmf-local/web2c/fmtutil.cnf
TEXMFDIST $TEXLIVE/YYYY/texmf-dist/web2c/fmtutil.cnf
(where YYYY is the TeX Live release version).
According to the actions, fmtutil might update one of the exist-
ing cnf files or create a new fmtutil.cnf, as described below.
Where format files are written:
By default, format files are (re)written in $TEXMFSYSVAR/ENGINE
by fmtutil-sys, and $TEXMFVAR/ENGINE by fmtutil-user, where /EN-
GINE is a subdirectory named for the engine used, such as "pdf-
tex".
For mktexfmt, TEXMFSYSVAR is used if it is writable, else TEXMF-
VAR.
If the --fmtdir=DIR option is specified, DIR is used instead of
TEXMF[SYS]VAR, but the /ENGINE subdir is still used by default.
In all cases, if the --no-engine-subdir option is specified, the
/ENGINE subdir is omitted.
Where configuration changes are saved:
If config files are given on the command line, then the first one
given will be used to save any changes from --enable or --dis-
able.
If the config files are taken from kpsewhich output, then the al-
gorithm is more complicated:
1) If $TEXMFCONFIG/web2c/fmtutil.cnf or $TEXMFHOME/web2c/fmtu-
til.cnf appears in the list of used files, then the one listed
first by kpsewhich --all (equivalently, the one returned by
"kpsewhich fmtutil.cnf"), is used.
2) If neither of the above two are present and changes are made,
a new config file is created in $TEXMFCONFIG/web2c/fmtutil.cnf.
In general, the idea is that if a given config file is not
writable, a higher-level one can be used. That way, the distrib-
ution's settings can be overridden system-wide using TEXMFLOCAL,
and system settings can be overridden again in a particular
user's TEXMFHOME or TEXMFCONF.
Resolving multiple definitions of a format:
If a format is defined in more than one config file, then the de-
finition coming from the first-listed fmtutil.cnf is used.
Disabling formats:
fmtutil.cnf files with higher priority (listed earlier) can dis-
able formats in lower priority (listed later) fmtutil.cnf files
by writing a line like this in the higher-priority fmtutil.cnf
file:
#! <fmtname> <enginename> <hyphen> <args>
The #! must be at the beginning of the line, with at least one
space or tab afterward, and there must be whitespace between each
word on the list.
For example, you can disable the luajitlatex format by creating
the file $TEXMFCONFIG/web2c/fmtutil.cnf with the line
#! luajitlatex luajittex language.dat,language.dat.lua luala-
tex.ini
(As it happens, the luajittex-related formats are precisely why
the --no-error-if-no-engine option exists, since luajittex cannot
be compiled on all platforms. So this is not needed.)
fmtutil-user (fmtutil -user) vs. fmtutil-sys (fmtutil -sys):
When fmtutil-sys is run or the command line option -sys is used,
TEXMFSYSCONFIG and TEXMFSYSVAR are used instead of TEXMFCONFIG
and TEXMFVAR, respectively. This is the primary difference be-
tween fmtutil-sys and fmtutil-user.
See https://tug.org/texlive/scripts-sys-user.html for details.
Other locations may be used if you give them on the command line,
or these trees don't exist, or you are not using the original TeX
Live.
Supporting development binaries:
If an engine name ends with "-dev", formats are created in the
respective directory with the -dev stripped. This allows for
easily running development binaries in parallel with the released
binaries.
ENVIRONMENT
This script runs TeX and Metafont to generate the fmt/base file,
and thus all normal environment variables and search path rules
for TeX/MF apply.
REPORTING BUGS
Report bugs to: tex-live@tug.org
TeX Live home page: <https://tug.org/texlive/>
TeX Live February 2024 FMTUTIL(1)
Generated by dwww version 1.16 on Tue Dec 16 05:55:46 CET 2025.