LUATEX(1)

📦 version 2026.0, in alpine 3.24

💅 LUATEX(1) — like, the whole manual, but make it make sense

okay bestie, so this is the LUATEX(1) page from the General Commands Manual, and it's genuinely a lot, but i got you 🫶 it's basically the glossary for the entire LuaTeX girlie squad and every single flag, so grab a strawberry drink and let's go ✨

🌸 NAME 🌸

luatex, dviluatex, luahbtex, luajithbtex, luajittex, texlua, texluac, texluajit, texluajitc — that's the whole friend group 💖 — and they're all TeX extended with Lua as an embedded scripting language. periodt.

✨ SYNOPSIS ✨

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

that's the shape of it, no cap 👑

🦋 DESCRIPTION 🦋

so what does it do? it runs the LuaTeX typesetter on file[.tex], and usually it creates file.pdf 💅 and yes — if your file argument has no extension, .tex just gets appended to it, automatically, iconic behavior. for the details of command-line parsing, go read tex(1), with the exceptions described here (important! don't skip that part 🎀).

LuaTeX lowkey started its life as an extended version of pdfTeX with lua(1) as an embedded scripting language, plus Unicode and OpenType/TrueType font support, the e-TeX and Omega extensions, and an integrated MetaPost library. it can generate either pdf or dvi output. wanna know more about LuaTeX? the home page is https://www.luatex.org — or you can just read the LuaTeX manual using the texdoc utility like so: texdoc luatex 📖

the unicode situation: all LuaTeX text input and output is read natively as Unicode text, although filters make it possible to support any encoding. 🪄 but caveat time, bestie, because this one matters: 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. like yes she can read the glyph, no she can't render it without the font, thems the rules 😭

the alter egos: if the program is called as texlua it acts as a Lua interpreter. if called as texluac it acts as a Lua bytecode compiler. same girl, different fit 💀

pdf vs dvi: by default, luatex produces pdf output, and dviluatex produces dvi output; both executables behave identically otherwise, within the limits of the output format. and both variants can be configured to produce either dvi or pdf output — flexible queens 👑

graphics tea ☕: 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 though, the PostScript files output by MetaPost can be handled directly via the supp-pdf.tex and supp-pdf.mkii macros. special little exception, we love her 🎀

which Lua is inside: 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 harfbuzz variant: the luahbtex variant includes the HarfBuzz engine for glyph shaping. heads up though — HarfBuzz must still be explicitly enabled at the TeX level. she doesn't just turn herself on, you have to invite her 💅

the primitives thing (important): 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), bestie, that's the homework.

and now the main character moment: 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. like, she's running a whole different script at that point, do not come for her 🫶
  • --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 💀 and 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.

then there's these two, and the original page literally says they alter the executable behaviour 👇 so pay attention:

  • --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. she's chill like that 🦋

and the safety girlies:

  • --safer — disable most file-modifying and program-executing Lua functions. this option is disabled by default since it breaks most documents. 😭 yeah. it's giving "protection that ruins the vibe."
  • --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). that's the whole section, she keeps it short and mysterious 💅

💀 BUGS 💀

see tex(1). literally just go look. 🙈

👑 SEE ALSO 👑

the whole extended universe, bestie:

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

and, like, numerous articles have been published in TUGboat about LuaTeX: https://tug.org/TUGboat/Contents — reading material for days 🍓

💖 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. absolute legends, all of them, no notes 🌟

and that's the page, bestie 🎀 this whole thing is Web2C 2026 energy, dated 14 February 2026 — a valentine to typesetting, honestly. mwah 💋 go typeset something iconic. 🦋✨

📦 where this page comes from
  • alpine 3.24: texmf-dist-doc 2026.0-r0 · LPPL-1.0 AND LPPL-1.1 AND LPPL-1.2 AND LPPL-1.3a AND LPPL-1.3c AND GPL-2.0-only
  • 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms