| 1 |
.TH LUATEX 1 "14 February 2026" "Web2C 2026" |
| 2 |
.\"===================================================================== |
| 3 |
.if t .ds TX \fRT\\h'-0.10m'\\v'0.17v'E\\v'-0.17v'\\h'-0.06m'X\fP |
| 4 |
.if n .ds TX TeX |
| 5 |
.\"===================================================================== |
| 6 |
.SH NAME |
| 7 |
luatex, dviluatex, luahbtex, luajithbtex, luajittex, texlua, texluac, texluajit, texluajitc \- TeX extended with Lua as an embedded scripting language |
| 8 |
.SH SYNOPSIS |
| 9 |
.B luatex |
| 10 |
.RB [ --lua=\fIluafile\fP ] |
| 11 |
\h'.25' |
| 12 |
.RI [ options ] |
| 13 |
.RI [ \fB&\fPformat ] |
| 14 |
\h'.25' [ \fIfile\fP [ \fImore-input\fP ] \h'.5'|\h'.5' [ \fB\e\fP\fImore-input\fP ] |
| 15 |
.\"===================================================================== |
| 16 |
.SH DESCRIPTION |
| 17 |
Run the Lua\*(TX typesetter on |
| 18 |
.IR file [.tex], |
| 19 |
usually creating |
| 20 |
.IR file\fB.pdf\fP . |
| 21 |
If the file argument has no extension, ".tex" will be appended to it. See |
| 22 |
.BR tex (1) |
| 23 |
for details of command-line parsing, with the exceptions described here. |
| 24 |
.PP |
| 25 |
Lua\*(TX began as an extended version of pdf\*(TX with \fBlua\fP(1) as |
| 26 |
an embedded scripting language, Unicode and OpenType/TrueType font |
| 27 |
support, the e-\*(TX and Omega extensions, as well as an integrated |
| 28 |
MetaPost library. It can generate either pdf or dvi output. For more |
| 29 |
information about Lua\*(TX, see https://www.luatex.org; or you can read |
| 30 |
the Lua\*(TX manual using the texdoc utility (\fBtexdoc luatex\fR). |
| 31 |
.PP |
| 32 |
All Lua\*(TX text input and output is read natively as Unicode text, |
| 33 |
although filters make it possible to support any encoding. Caveat: just |
| 34 |
because any Unicode character can be recognized as input does not mean |
| 35 |
it can be typeset as output; you still have to load the necessary fonts. |
| 36 |
.PP |
| 37 |
If the program is called as \fBtexlua\fR it acts as a Lua interpreter. |
| 38 |
If called as \fBtexluac\fR it acts as a Lua bytecode compiler. |
| 39 |
.PP |
| 40 |
By default, \fBluatex\fP produces pdf output, and \fBdviluatex\fP |
| 41 |
produces dvi output; both executables behave identically otherwise, |
| 42 |
within the limits of the output format. Both variants can be configured |
| 43 |
to produce either dvi or pdf output. |
| 44 |
.PP |
| 45 |
In pdf mode, Lua\*(TX can natively handle the pdf, jpg, jbig2, and png |
| 46 |
graphics formats, but not PostScript or Encapsulated PostScript (eps) |
| 47 |
graphics; see |
| 48 |
.BR pdftex (1). |
| 49 |
As a special case, the PostScript files output by MetaPost can be |
| 50 |
handled directly via the \fIsupp-pdf.tex\fP and \fIsupp-pdf.mkii\fP macros. |
| 51 |
.PP |
| 52 |
The regular \fBluatex\fP programs embed Lua 5.3, developed by PUC-Rio; |
| 53 |
the \fBjit\fP variants such as \fBluajittex\fP embed LuaJIT for |
| 54 |
just-in-time compilation, developed by Mike Pall. |
| 55 |
.PP |
| 56 |
The \fBluahbtex\fP variant includes the HarfBuzz engine for glyph |
| 57 |
shaping. HarfBuzz must still be explicitly enabled at the \*(TX level. |
| 58 |
.PP |
| 59 |
By default, Lua\*(TX does not provide any primitives beyond those from |
| 60 |
\*(TX3. All extended primitives must be enabled at runtime using |
| 61 |
\edirectlua; see the Lua\*(TX manual and existing format-building files, |
| 62 |
e.g., luatex.ini. |
| 63 |
.\"===================================================================== |
| 64 |
.SH "OPTIONS" |
| 65 |
For the common \*(TX command-line options and handling, see |
| 66 |
.BR tex (1). |
| 67 |
.PP |
| 68 |
When the Lua\*(TX executable starts, it looks for the \fB--lua\fR |
| 69 |
command-line option. If there is no \fB--lua\fR option, the command line |
| 70 |
is interpreted similarly to traditional pdf\*(TX and Aleph. But if the |
| 71 |
option is present, Lua\*(TX will enter an alternative mode of |
| 72 |
command-line parsing, unrelated to the standard Web2C programs. The |
| 73 |
presence of \fB--lua\fR thus makes all other options unreliable, because |
| 74 |
the Lua initialization file can disable the default file searching via |
| 75 |
Kpathsea and/or hook functions into various callbacks. |
| 76 |
.TP |
| 77 |
.BI "--lua=" luafile |
| 78 |
The Lua initialization file. The Lua\*(TX executables embed a default |
| 79 |
initialization file (luatex-core.lua); if this option is used, |
| 80 |
\fIluafile\fP will be used instead. The Lua initialization file is |
| 81 |
responsible for setting up security restrictions, path searching |
| 82 |
behaviour, and other low-level settings, so you must be careful when |
| 83 |
using a custom file or else you will likely crash the engine. If this |
| 84 |
option is used, you must pass the same file both when dumping the format |
| 85 |
and when typesetting a document. This option is used by Con\*(TXt. |
| 86 |
.PP |
| 87 |
The following two options alter the executable behaviour: |
| 88 |
.TP |
| 89 |
.B --luaonly |
| 90 |
Start Lua\*(TX as a Lua interpreter. In this mode, it will set Lua's |
| 91 |
\fIarg[0]\fR to the found script name, pushing preceding options in |
| 92 |
negative values and the rest of the command line in the positive values, |
| 93 |
just like the Lua interpreter. Lua\*(TX will exit immediately after |
| 94 |
executing the specified Lua script. |
| 95 |
.TP |
| 96 |
.BI --luaconly |
| 97 |
Start Lua\*(TX as a Lua bytecode compiler. In this mode, Lua\*(TX is exactly |
| 98 |
like \fBluac\fR from the standalone Lua distribution, except that it |
| 99 |
does not have the \fB-l\fR switch, and that it accepts and ignores |
| 100 |
the \fB--luaconly\fR switch. |
| 101 |
.TP |
| 102 |
.B --safer |
| 103 |
Disable most file-modifying and program-executing Lua functions. |
| 104 |
This option is disabled by default since it breaks most |
| 105 |
documents. |
| 106 |
.TP |
| 107 |
.B --luadebug |
| 108 |
Enables the standard Lua \fIdebug\fP module, which is disabled by |
| 109 |
default for security reasons. This option is implicitly enabled |
| 110 |
when unrestricted shell-escape is enabled. |
| 111 |
.TP |
| 112 |
.B --[no-]socket |
| 113 |
Enables the Lua \fIsocket\fP module, which allows \*(TX documents to |
| 114 |
make arbitrary network requests, and is disabled by default for |
| 115 |
security reasons. This option is implicitly enabled when |
| 116 |
unrestricted shell escape is enabled. |
| 117 |
.\"===================================================================== |
| 118 |
.SH ENVIRONMENT |
| 119 |
See |
| 120 |
.BR tex (1) |
| 121 |
and |
| 122 |
.BR pdftex (1). |
| 123 |
.SH BUGS |
| 124 |
See |
| 125 |
.BR tex (1). |
| 126 |
.\"===================================================================== |
| 127 |
.SH "SEE ALSO" |
| 128 |
.BR aleph (1), |
| 129 |
.BR etex (1), |
| 130 |
.BR lua (1), |
| 131 |
.BR mpost (1), |
| 132 |
.BR pdftex (1), |
| 133 |
.BR tex (1). |
| 134 |
.PP |
| 135 |
Lua\*(TX home page: https://luatex.org |
| 136 |
.br |
| 137 |
Package page on CTAN: https://ctan.org/pkg/luatex |
| 138 |
.br |
| 139 |
Lua\*(TX reference manual: https://mirror.ctan.org/systems/doc/luatex/luatex.pdf |
| 140 |
.br |
| 141 |
Web2c manual: https://tug.org/web2c |
| 142 |
.br |
| 143 |
Kpathsea manual: https://tug.org/kpathsea |
| 144 |
.PP |
| 145 |
Numerous articles have been published in \fITUGboat\fP about Lua\*(TX: |
| 146 |
https://tug.org/TUGboat/Contents |
| 147 |
.\"===================================================================== |
| 148 |
.SH "AUTHORS" |
| 149 |
\*(TX was created by Donald E. Knuth. |
| 150 |
The primary authors of the Lua\*(TX enhancements are Taco Hoekwater, |
| 151 |
Hartmut Henkel, Hans Hagen, and Luigi Scarso, with help from Martin |
| 152 |
Schr\[:o]der, Karel Skoup\['y], and H\[`a]n The Th\[`a]nh. |
| 153 |
.\" the double accent 0x1EBF in Thanh's name is not easily available. |
| 154 |
.PP |
| 155 |
Bug reports: [email protected] |
| 156 |
.br |
| 157 |
Public discussion list for Lua\*(TX-specific issues: |
| 158 |
https://lists.tug.org/luatex |
| 159 |
.br |
| 160 |
Public discussion list for all things \*(TX: |
| 161 |
https://lists.tug.org/texhax |