Debian Codegraph @

texmf-dist/doc/man/man1/luatex.1

raw
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