Provided by: texlive-luatex_2024.20250309-1_all 
NAME
luaotfload.conf - Luaotfload configuration file
SYNOPSIS
• ./luaotfload{.conf,rc}
• XDG_CONFIG_HOME/luaotfload/luaotfload{.conf,rc}
• ~/.luaotfloadrc
DESCRIPTION
The file luaotfload.conf contains configuration options for Luaotfload, a font loading and font
management component for LuaTeX.
EXAMPLE
A small Luaotfload configuration file with few customizations could look as follows:
[db]
formats = afm,ttf
compress = false
[misc]
termwidth = 60
[run]
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 ./luaotfload.conf 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.
SYNTAX
The configuration file syntax follows the common INI format. For a more detailed description please refer
to the section “CONFIGURATION FILE” of git-config(1). A brief list of rules is given below:
• Blank lines and lines starting with a semicolon (;) are ignored.
• A configuration file is partitioned into sections that are declared by specifying the section title
in brackets on a separate line:
[some-section]
... section content ...
• Sections consist of one or more variable assignments of the form variable-name = value E. g.:
[foo]
bar = baz
quux = xyzzy
...
• Section and variable names may contain only uppercase and lowercase letters as well as dashes (-).
VARIABLES
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
post_linebreak_filter, pre_linebreak_filter, or pre_output_filter, defined in the section run of the
configuration file.
Currently, the configuration is organized into four sections:
db Options relating to the font index.
misc Options without a clearly defined category.
paths Path and file name settings.
run 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 type,
n for number, b for boolean. A value of nil means the variable is unset.
Section db
┌─────────────────────┬──────┬─────────────────────┐
│ variable │ type │ default │
├─────────────────────┼──────┼─────────────────────┤
│ compress │ b │ true │
├─────────────────────┼──────┼─────────────────────┤
│ designsize-dimen │ b │ bp │
├─────────────────────┼──────┼─────────────────────┤
│ formats │ s │ "otf,ttf,ttc" │
├─────────────────────┼──────┼─────────────────────┤
│ location-precedence │ s │ "system,texmf,local │
├─────────────────────┼──────┼─────────────────────┤
│ max-fonts │ n │ 2^51 │
├─────────────────────┼──────┼─────────────────────┤
│ scan-local │ b │ false │
├─────────────────────┼──────┼─────────────────────┤
│ skip-read │ b │ false │
├─────────────────────┼──────┼─────────────────────┤
│ strip │ b │ true │
├─────────────────────┼──────┼─────────────────────┤
│ update-live │ b │ true │
└─────────────────────┴──────┴─────────────────────┘
The flag compress determines whether the font index (usually luaotfload-names.lua[.gz] will be stored in
compressed forms. If unset it is equivalent of passing --no-compress to luaotfload-tool. 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. In Opentype,
these are specified as “decipoints” where one decipoint equals ten DTP style “big points”. When indexing
fonts these values are converted to sp. In order to treat the values as though they were specified in TeX
points or Didot points, set designsize-dimen to pt or 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" will be
used.
The variable location-precedence selects where and in which order luaotfload searches for fonts. Fonts in
earlier locations are preferred. The three supported locations are system for system specific font
directories, texmf for fonts which are part of the TeX{} distribution and local for local fonts.
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
--max-fonts to luaotfload-tools.
The scan-local 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 built. Setting
scan_local to false is the same as removing local from location-precedence.
The skip-read 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 behavior.
If update-live is set, Luaotfload will reload the database if it cannot find a requested font. Those who
prefer to update manually using luaotfload-tool should unset this flag. This option does not affect
rebuilds due to version mismatch.
Section default-features
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
[default-features]
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 to true.
Section misc
┌────────────┬──────┬──────────────────────┐
│ variable │ type │ default │
├────────────┼──────┼──────────────────────┤
│ statistics │ b │ false │
├────────────┼──────┼──────────────────────┤
│ termwidth │ n │ nil │
├────────────┼──────┼──────────────────────┤
│ version │ s │ <Luaotfload version> │
├────────────┼──────┼──────────────────────┤
│ keepnames │ b │ true │
└────────────┴──────┴──────────────────────┘
With statistics 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 keepnames option decides if the ConTeXt fontloader should keep names it considers useless or if they
should be discarded. This option only takes effect after font caches are regenererated.
Section paths
───────────────────────────────────────────────────────
variable type default
───────────────────────────────────────────────────────
cache-dir s "fonts"
───────────────────────────────────────────────────────
names-dir s "names"
───────────────────────────────────────────────────────
index-file s "luaotfload-names.lua"
───────────────────────────────────────────────────────
lookups-file s "luaotfload-lookup-cache.lua"
┌──────────────┬──────┬───────────────────────────────┐
│ │ │ │
--
FILES
Luaotfload only processes the first configuration file it encounters at one of the search locations. The
file name may be either luaotfload.conf or luaotfloadrc, 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
i. The current working directory of the LuaTeX process.
ii. The subdirectory luaotfload/ inside the XDG configuration tree, e. g.
/home/oenothea/config/luaotfload/.
iii. The dotfile.
iv. The TEXMF (using kpathsea).
SEE ALSO
luaotfload-tool(1), luatex(1), lua(1)
• texdoc luaotfload to display the PDF manual for the Luaotfload package
• Luaotfload development https://github.com/latex3/luaotfload
• LuaLaTeX mailing list http://tug.org/pipermail/lualatex-dev/
• LuaTeX http://luatex.org/
• Luaotfload on CTAN http://ctan.org/pkg/luaotfload
REFERENCES
• The XDG base specification http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html.
AUTHORS
Luaotfload was developed by the LuaLaTeX dev team (https://github.com/lualatex/). It is currently
maintained by the LaTeX Project Team at https://github.com/latex3/luaotfload
This manual page was written by Philipp Gesang <phg@phi-gamma.net>.
COPYRIGHT
GPL v2.0
3.29 2024-12-03 LUAOTFLOAD.CONF(5)