LUATEX(1)

NAME
luatex, dviluatex, luahbtex, luajithbtex, luajittex, texlua, texluac, texluajit, texluajitc - TeX extended with Lua as an embedded scripting language

SYNOPSIS
luatex [--lua=luafile] [options] [&format] [ file [ more-input ] | [ \more-input ]

DESCRIPTION
Run the LuaTeX typesetter on file[.tex], usually creating file.pdf. If the file argument has no extension, ".tex" will be appended to it. See tex(1) for details of command-line parsing, with the exceptions described here.

LuaTeX began as an extended version of pdfTeX with lua(1) as an embedded scripting language, Unicode and OpenType/TrueType font support, the e-TeX and Omega extensions, as well as an integrated MetaPost library. It can generate either pdf or dvi output. For more information about LuaTeX, see https://www.luatex.org; or you can read the LuaTeX manual using the texdoc utility (texdoc luatex).

All LuaTeX text input and output is read natively as Unicode text, although filters make it possible to support any encoding. Caveat: just because any Unicode character can be recognized as input does not mean it can be typeset as output; you still have to load the necessary fonts.

If the program is called as texlua it acts as a Lua interpreter. If called as texluac it acts as a Lua bytecode compiler.

By default, luatex produces pdf output, and dviluatex produces dvi output; both executables behave identically otherwise, within the limits of the output format. Both variants can be configured to produce either dvi or pdf output.

In pdf mode, LuaTeX can natively handle the pdf, jpg, jbig2, and png graphics formats, but not PostScript or Encapsulated PostScript (eps) graphics; see pdftex(1). As a special case, the PostScript files output by MetaPost can be handled directly via the supp-pdf.tex and supp-pdf.mkii macros.

The regular luatex programs embed Lua 5.3, developed by PUC-Rio; the jit variants such as luajittex embed LuaJIT for just-in-time compilation, developed by Mike Pall.

The luahbtex variant includes the HarfBuzz engine for glyph shaping. HarfBuzz must still be explicitly enabled at the TeX level.

By default, LuaTeX does not provide any primitives beyond those from TeX3. All extended primitives must be enabled at runtime using \directlua; see the LuaTeX manual and existing format-building files, e.g., luatex.ini.

OPTIONS
For the common TeX command-line options and handling, see tex(1).

When the LuaTeX executable starts, it looks for the --lua command-line option. If there is no --lua option, the command line is interpreted similarly to traditional pdfTeX and Aleph. But if the option is present, LuaTeX will enter an alternative mode of command-line parsing, unrelated to the standard Web2C programs. The presence of --lua thus makes all other options unreliable, because the Lua initialization file can disable the default file searching via Kpathsea and/or hook functions into various callbacks.

--lua=luafile
    The Lua initialization file. The LuaTeX executables embed a default initialization file (luatex-core.lua); if this option is used, luafile will be used instead. The Lua initialization file is responsible for setting up security restrictions, path searching behaviour, and other low-level settings, so you must be careful when using a custom file or else you will likely crash the engine. If this option is used, you must pass the same file both when dumping the format and when typesetting a document. This option is used by ConTeXt.

The following two options alter the executable behaviour:

--luaonly
    Start LuaTeX as a Lua interpreter. In this mode, it will set Lua's arg[0] to the found script name, pushing preceding options in negative values and the rest of the command line in the positive values, just like the Lua interpreter. LuaTeX will exit immediately after executing the specified Lua script.

--luaconly
    Start LuaTeX as a Lua bytecode compiler. In this mode, LuaTeX is exactly like luac from the standalone Lua distribution, except that it does not have the -l switch, and that it accepts and ignores the --luaconly switch.

--safer
    Disable most file-modifying and program-executing Lua functions. This option is disabled by default since it breaks most documents.

--luadebug
    Enables the standard Lua debug module, which is disabled by default for security reasons. This option is implicitly enabled when unrestricted shell-escape is enabled.

--[no-]socket
    Enables the Lua socket module, which allows TeX documents to make arbitrary network requests, and is disabled by default for security reasons. This option is implicitly enabled when unrestricted shell escape is enabled.

ENVIRONMENT
See tex(1) and pdftex(1).

BUGS
See tex(1).

SEE ALSO
aleph(1), etex(1), lua(1), mpost(1), pdftex(1), tex(1).

LuaTeX home page: https://luatex.org
Package page on CTAN: https://ctan.org/pkg/luatex
LuaTeX reference manual: https://mirror.ctan.org/systems/doc/luatex/luatex.pdf
Web2c manual: https://tug.org/web2c
Kpathsea manual: https://tug.org/kpathsea

Numerous articles have been published in TUGboat about LuaTeX: https://tug.org/TUGboat/Contents

AUTHORS
TeX was created by Donald E. Knuth. The primary authors of the LuaTeX enhancements are Taco Hoekwater, Hartmut Henkel, Hans Hagen, and Luigi Scarso, with help from Martin Schröder, Karel Skoupý, and Hàn The Thành.

Bug reports: dev-luatex@ntg.nl
Public discussion list for LuaTeX-specific issues: https://lists.tug.org/luatex
Public discussion list for all things TeX: https://lists.tug.org/texhax