luaotfload.conf - Luaotfload configuration file
The file luaotfload.conf
contains configuration options for
, a font loading and font management component for LuaTeX.
A small Luaotfload configuration file with few customizations could look as
formats = afm,ttf
compress = false
termwidth = 60
log-level = 6
This will make Luaotfload ignore all font files except for PostScript binary
fonts with a matching AFM file, and Truetype fonts. Also, an uncompressed
index file will be dumped which is going to be much larger than the default
gzip’ed index. The terminal width is truncated to 60 characters which
influences the verbose output during indexing. Finally, the verbosity is
increased greatly: each font file being processed will be printed to the
stdout on a separate line, along with lots of other information.
To observe the difference in behavior, save above snippet to
and update the font index:
luaotfload-tool --update --force
The current configuration can be written to disk using luaotfload-tool
luaotfload-tool --dumpconf > luaotfload.conf
The result can itself be used as a configuration file.
The configuration file syntax follows the common INI format. For a more detailed
description please refer to the section “CONFIGURATION FILE” of
(1). A brief list of rules is given below:
- Blank lines and lines starting with a semicolon (;)
- A configuration file is partitioned into sections that are
declared by specifying the section title in brackets on a separate
... section content ...
- Sections consist of one or more variable assignments of the
form variable-name = value E. g.:
bar = baz
quux = xyzzy
- Section and variable names may contain only uppercase and
lowercase letters as well as dashes ( -).
Variables in belong into a configuration section and their values must be of a
certain type. Some of them have further constraints. For example, the
“color callback” must be a string of one of the values
, defined in the section run
Currently, the configuration is organized into four sections:
- Options relating to the font index.
- Options without a clearly defined category.
- Path and file name settings.
- Options controlling runtime behavior of Luaotfload.
The list of valid variables, the sections they are part of and their type is
given below. Types represent Lua types that the values must be convertible to;
they are abbreviated as follows: s
for the string
. A value of nil
the variable is unset.
The flag compress
determines whether the font index (usually
will be stored in compressed forms. If unset
it is equivalent of passing --no-compress
Since the file is only created for convenience and has no effect on the
runtime behavior of Luaotfload, the flag should remain set. Most editors come
with zlib support anyways.
The setting designsize-dimen
applies when looking up fonts from families
with design sizes. The default of DTP-style “big points” can be
changed for pt
or even dd
The list of formats
must be a comma separated sequence of strings
containing one or more of these elements:
- otf (OpenType format),
- ttf and ttc (TrueType format),
- afm (Adobe Font Metrics),
It corresponds loosely to the --formats
option to luaotfload-tool
Invalid or duplicate members are ignored; if the list does not contain any
useful identifiers, the default list "otf,ttf,ttc"
The variable max-fonts
determines after processing how many font files
the font scanner will terminate the search. This is useful for debugging
issues with the font index and has the same effect as the option
flag, if set, will incorporate the current working
directory as a font search location. NB: This will potentially slow down
document processing because a font index with local fonts will not be saved to
disk, so these fonts will have to be re-indexed whenever the document is
flag is only useful for debugging: It makes Luaotfload skip
reading fonts. The font information for rebuilding the index is taken from the
presently existing one.
Unsetting the strip
flag prevents Luaotfload from removing data from the
index that is only useful when processing font files. NB: this can increase
the size of the index files significantly and has no effect on the runtime
is set, Luaotfload will reload the database if it cannot
find a requested font. Those who prefer to update manually using
should unset this flag. This option does not affect
rebuilds due to version mismatch.
By default Luaotfload enables node
mode and picks the default font
features that are prescribed in the OpenType standard. This behavior may be
overridden in the default-features
section. Global defaults that will
be applied for all scripts can be set via the global
option, others by
the script they are to be applied to. For example, a setting of
global = mode=base,color=0000FF
dflt = smcp,onum
would force base
mode, tint all fonts blue and activate small capitals
and text figures globally. Features are specified as a comma separated list of
variables or variable-value pairs. Variables without an explicit value are set
enabled, extra statistics will be collected during index
creation and appended to the index file. It may then be queried at the Lua end
or inspected by reading the file itself.
The value of termwidth
, if set, overrides the value retrieved by querying
the properties of the terminal in which Luatex runs. This is useful if the
engine runs with shell_escape
disabled and the actual terminal
dimensions cannot be retrieved.
The value of version
is derived from the version string hard-coded in the
Luaotfload source. Override at your own risk.
The paths cache-dir
determine the subdirectory
inside the Luaotfload subtree of the luatex-cache
directory where the
font cache and the font index will be stored, respectively.
Inside the index directory, the names of the index file and the font lookup
cache will be derived from the respective values of index-file
. This is the filename base for the bytecode compiled
version as well as -- for the index -- the gzipped version.
Unqualified font lookups are treated with the flexible “anonymous”
mechanism. This involves a chain of lookups applied successively until the
first one yields a match. By default, the lookup will first search for TFM
fonts using the Kpathsea library. If this wasn’t successful, an attempt
is made at interpreting the request as an absolute path (like the
syntax) or a file name ( file:foo.ttf
Finally, the request is interpreted as a font name and retrieved from the
index ( name:Foo Regular
). This behavior can be configured by
specifying a list as the value to anon-sequence
. Available items are
-- representing the lookups described
above, respectively --, and file
for searching a filename but not an
absolute path. Also, my
lookups are valid values but they should only
be used from within TeX documents, because there is no means of customizing a
lookups on the command line.
option determines the stage at which fonts that
defined with a color=xxyyzz
feature will be colorized. By default this
happens in a post_linebreak_filter
but alternatively the
may be chosen, which
is faster but might produce inconsistent output. The pre_output_filter
used to be the default in the 1.x series of Luaotfload, whilst later versions
up to and including 2.5 hooked into the pre_linebreak_filter
naturally didn’t affect any glyphs inserting during hyphenation. Both
are kept around as options to restore the previous behavior if necessary.
allows for switching the define_font
from the default patch
one may also choose the generic
comes with the vanilla fontloader. Beware that this might break tools like
Fontspec that rely on the patch_font
callback provided by Luaotfload to
perform important corrections on font data.
The fontloader backend can be selected by setting the value of
. The most important choices are default
, which will
load the dedicated Luaotfload fontloader, and reference
, the upstream
package as shipped with Luaotfload. Other than those, a file name accessible
via kpathsea can be specified.
Alternatively, the individual files that constitute the fontloader can be loaded
directly. While less efficient, this greatly aids debugging since error
messages will reference the actual line numbers of the source files and
explanatory comments are not stripped. Currently, three distinct loading
strategies are available: unpackaged
will load the batch that is part
of Luaotfload. These contain the identical source code that the reference
fontloader has been compiled from. Another option, context
to load the same files by their names in the Context format from the search
path. Consequently this option allows to use the version of Context that comes
with the TeX distribution. Distros tend to prefer the stable version
(“current” in Context jargon) of those files so certain bugs
encountered in the more bleeding edge Luaotfload can be avoided this way. A
third option is to use context
with a colon to specify a directory
prefix where the TEXMF
is located that the files should be loaded from,
e. g. context:~/context/tex/texmf-context
. This can be used when
referencing another distribution like the Context minimals that is installed
under a different path not indexed by kpathsea.
The value of log-level
sets the default verbosity of messages printed by
Luaotfload. Only messages defined with a verbosity of less than or equal to
the supplied value will be output on the terminal. At a log level of five
Luaotfload can be very noisy. Also, printing too many messages will slow down
the interpreter due to line buffering being disabled (see setbuf
setting allows choosing the font name resolution function:
With the default value cached
Luaotfload saves the result of a
successful font name request to a cache file to speed up subsequent lookups.
The alternative, normal
circumvents the cache and resolves every
request individually. (Since to the restructuring of the font name index in
Luaotfload 2.4 the performance difference between the cached and uncached
lookups should be marginal.)
Luaotfload only processes the first configuration file it encounters at one of
the search locations. The file name may be either luaotfload.conf
, except for the dotfile in the user’s home
directory which is expected at ~/.luaotfloadrc
Configuration files are located following a series of steps. The search
terminates as soon as a suitable file is encountered. The sequence of
locations that Luaotfload looks at is
- The current working directory of the LuaTeX process.
- The subdirectory luaotfload/ inside the XDG
configuration tree, e. g. /home/oenothea/config/luaotfload/.
- The dotfile.
- The TEXMF (using kpathsea).
- texdoc luaotfload to display the PDF manual for the
- Luaotfload development
- LuaLaTeX mailing list
- LuaTeX http://luatex.org/
- Luaotfload on CTAN
- The XDG base specification
is maintained by the LuaLaTeX dev team (
This manual page was written by Philipp Gesang <