Debian Codegraph @

texmf-dist/doc/man/man1/install-tl.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "INSTALL-TL 1"
61 .TH INSTALL-TL 1 2026-04-10 "perl v5.42.2" "User Contributed Perl Documentation"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 install\-tl \- TeX Live cross\-platform installer
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 install\-tl [\fIoption\fR]...
71 .PP
72 install\-tl\-windows.bat [\fIoption\fR]...
73 .SH DESCRIPTION
74 .IX Header "DESCRIPTION"
75 This installer creates a runnable TeX Live installation from various
76 media, including over the network, from local hard disk, a DVD, etc. The
77 installer works on all platforms supported by TeX Live. For information
78 on initially downloading TeX Live, see
79 <https://tug.org/texlive/acquire.html>.
80 .PP
81 The basic idea of TeX Live installation is for you to choose one of the
82 top\-level \fIschemes\fR, each of which is defined as a different set of
83 \&\fIcollections\fR and \fIpackages\fR, where a collection is a set of packages,
84 and a package is what contains actual files. Each package is in exactly
85 one collection, while schemes can contain any combination of packages
86 and collections.
87 .PP
88 Within the installer, you can choose a scheme, and further customize the
89 set of collections to install, but not the set of the packages. To work
90 at the package level, use \f(CW\*(C`tlmgr\*(C'\fR (reference just below) after the
91 initial installation is complete.
92 .PP
93 The default is \f(CW\*(C`scheme\-full\*(C'\fR, which installs everything, and this is
94 highly recommended.
95 .SH REFERENCES
96 .IX Header "REFERENCES"
97 Post\-installation configuration, package updates, and more, are
98 handled through \fBtlmgr\fR(1), the TeX Live Manager
99 (<https://tug.org/texlive/tlmgr.html>).
100 .PP
101 The most up\-to\-date version of this installer documentation is on the
102 Internet at <https://tug.org/texlive/doc/install\-tl.html>.
103 .PP
104 For step\-by\-step instructions, see
105 <https://tug.org/texlive/quickinstall.html>.
106 .PP
107 For the full documentation of TeX Live, see
108 <https://tug.org/texlive/doc>.
109 .SH EXAMPLES
110 .IX Header "EXAMPLES"
111 With no options, \f(CW\*(C`install\-tl\*(C'\fR drops you into an interactive menu where
112 essentially all default settings can be changed. With options, you can
113 initialize the settings in various ways, or perform the installation
114 without interaction. Some examples:
115 .ie n .IP """install\-tl \-\-paper=letter""" 4
116 .el .IP "\f(CWinstall\-tl \-\-paper=letter\fR" 4
117 .IX Item "install-tl --paper=letter"
118 Initialize paper size setting. The only values allowed are \f(CW\*(C`letter\*(C'\fR and
119 (the default) \f(CW\*(C`a4\*(C'\fR.
120 .ie n .IP """install\-tl \-\-scheme"" \fIscheme\fR" 4
121 .el .IP "\f(CWinstall\-tl \-\-scheme\fR \fIscheme\fR" 4
122 .IX Item "install-tl --scheme scheme"
123 Initialize the installation scheme; the default is \f(CW\*(C`full\*(C'\fR. For a list
124 of schemes, see the interactive \f(CW\*(C`S\*(C'\fR menu.
125 .ie n .IP """install\-tl \-\-no\-interaction""" 4
126 .el .IP "\f(CWinstall\-tl \-\-no\-interaction\fR" 4
127 .IX Item "install-tl --no-interaction"
128 Perform the installation immediately after parsing options, without
129 entering the interactive menu.
130 .ie n .IP """install\-tl \-\-profile"" \fItexlive.profile\fR" 4
131 .el .IP "\f(CWinstall\-tl \-\-profile\fR \fItexlive.profile\fR" 4
132 .IX Item "install-tl --profile texlive.profile"
133 Install, without interaction, according to the given TL profile file;
134 see "PROFILES" below. To initialize from the profile and then enter the
135 interactive menu, add \f(CW\*(C`\-\-init\-from\-profile\*(C'\fR.
136 .PP
137 Full documentation follows.
138 .SH OPTIONS
139 .IX Header "OPTIONS"
140 As usual, all options can be specified in any order, and with either a
141 leading \f(CW\*(C`\-\*(C'\fR or \f(CW\*(C`\-\-\*(C'\fR. An argument value can be separated from its
142 option by either a space or \f(CW\*(C`=\*(C'\fR.
143 .PP
144 The options relating to customization of the installation can also be
145 selected in the interactive installation menus (GUI or text).
146 .IP "\fB\-gui\fR [[=]\fImodule\fR]" 4
147 .IX Item "-gui [[=]module]"
148 .PD 0
149 .IP \fB\-no\-gui\fR 4
150 .IX Item "-no-gui"
151 .PD
152 If no \fImodule\fR is given, starts the Tcl/Tk (see below) GUI installer.
153 .Sp
154 If \fImodule\fR is given loads the given installer module. Currently the
155 following modules are supported:
156 .RS 4
157 .ie n .IP """text""" 4
158 .el .IP \f(CWtext\fR 4
159 .IX Item "text"
160 The text mode user interface (default on Unix systems, including Macs).
161 Same as the \f(CW\*(C`\-no\-gui\*(C'\fR option.
162 .ie n .IP """tcl"" (or ""perltk"" or ""wizard"" or ""expert"" or nothing)" 4
163 .el .IP "\f(CWtcl\fR (or ""perltk"" or ""wizard"" or ""expert"" or nothing)" 4
164 .IX Item "tcl (or ""perltk"" or ""wizard"" or ""expert"" or nothing)"
165 The Tcl/Tk user interface (default on Windows). It starts
166 with a small number of configuration options, roughly equivalent
167 to what the former wizard option offers, but a button \f(CW\*(C`Advanced\*(C'\fR
168 takes you to a screen with roughly the same options as the former
169 \&\f(CW\*(C`perltk\*(C'\fR interface.
170 .RE
171 .RS 4
172 .Sp
173 The default GUI requires Tcl/Tk. This was standard on Macs, but has been
174 removed in the latest macOS releases. It\*(Aqs often already installed on
175 GNU/Linux, or can be easily installed through a distro package manager.
176 For Windows, TeX Live provides a Tcl/Tk runtime.
177 .RE
178 .IP "\fB\-lang\fR \fIllcode\fR" 4
179 .IX Item "-lang llcode"
180 By default, the Tcl GUI uses the language detection built into
181 Tcl/Tk. If that fails you can select a different language by
182 giving this option with a language code (based on ISO 639\-1).
183 Currently supported (but not necessarily completely translated) are:
184 English (en, default), Czech (cs), German (de), French (fr), Italian
185 (it), Japanese (ja), Dutch (nl), Polish (pl), Brazilian Portuguese
186 (pt_BR), Russian (ru), Slovak (sk), Slovenian (sl), Serbian (sr),
187 Ukrainian (uk), Vietnamese (vi), simplified Chinese (zh_CN), and
188 traditional Chinese (zh_TW).
189 .IP "\fB\-repository\fR \fIurl|path\fR" 4
190 .IX Item "-repository url|path"
191 Specify the package repository to be used as the source of the
192 installation. In short, this can be a directory name or a url using
193 http(s), ftp, or scp. The documentation for \f(CW\*(C`tlmgr\*(C'\fR has the details
194 (<https://tug.org/texlive/doc/tlmgr.html#OPTIONS>).
195 .Sp
196 For installation, the default is to pick a mirror automatically, using
197 <https://mirror.ctan.org/systems/texlive/tlnet>; the chosen mirror is
198 then used for the entire download. You can use the special argument
199 \&\f(CW\*(C`ctan\*(C'\fR as an abbreviation for this. (See <https://ctan.org> for more
200 about CTAN and its mirrors.)
201 .Sp
202 After installation is complete, you can use that installation as the
203 repository for another installation. If you chose to install less than
204 the full scheme containing all packages, the list of available schemes
205 will be adjusted accordingly.
206 .IP \fB\-select\-repository\fR 4
207 .IX Item "-select-repository"
208 This option allows you to choose a particular mirror from the current
209 list of active CTAN mirrors. This option is supported in the \f(CW\*(C`text\*(C'\fR
210 and \f(CW\*(C`gui\*(C'\fR installer modes, and will also offer to install
211 from local media if available, or from a repository specified on the
212 command line. It\*(Aqs useful when the (default) automatic redirection does
213 not choose a good host for you.
214 .IP \fB\-all\-options\fR 4
215 .IX Item "-all-options"
216 Normally options not relevant to the current platform are not shown
217 (e.g., when running on Unix, Windows\-specific options are omitted).
218 Giving this command line option allows configuring such "foreign"
219 settings.
220 .IP "\fB\-custom\-bin\fR \fIpath\fR" 4
221 .IX Item "-custom-bin path"
222 If you have built your own set of TeX Live binaries (e.g., because
223 precompiled binaries were not provided by TL for your platform), this
224 option allows you to specify the \fIpath\fR to a directory where the
225 binaries for the current system are present. The installation will
226 continue as usual, but at the end all files from \fIpath\fR are copied over
227 to \f(CW\*(C`bin/custom/\*(C'\fR under your installation directory and this
228 \&\f(CW\*(C`bin/custom/\*(C'\fR directory is what will be added to the path for the
229 post\-install actions. To install multiple custom binary sets, manually
230 rename \f(CW\*(C`custom\*(C'\fR before doing each.
231 .Sp
232 For more information on custom binaries, see
233 <https://tug.org/texlive/custom\-bin.html>. For general information on
234 building TeX Live, see <https://tug.org/texlive/build.html>.
235 .IP \fB\-debug\-fakenet\fR 4
236 .IX Item "-debug-fakenet"
237 Pretend we\*(Aqre doing a network install. This is for the sole purpose of
238 testing the code to handle broken downloads, via moving package files
239 aside in a tlnet mirror hierarchy.
240 .IP \fB\-debug\-setup\-vars\fR 4
241 .IX Item "-debug-setup-vars"
242 Print final values of directory variables; for more debugging
243 information on how they were set, also specify \f(CW\*(C`\-v\*(C'\fR.
244 .IP \fB\-debug\-translation\fR 4
245 .IX Item "-debug-translation"
246 In the former Perl/Tk GUI modes, this option reported any missing,
247 or more likely untranslated, messages to standard error. Not yet
248 implemented for the Tcl interface. Helpful for translators to see
249 what remains to be done.
250 .IP "\fB\-force\-platform\fR \fIplatform\fR" 4
251 .IX Item "-force-platform platform"
252 Instead of auto\-detecting the current platform, use \fIplatform\fR.
253 Binaries for this platform must be present in \f(CW\*(C`bin/\*(C'\fR\fIplatform\fR\f(CW\*(C`/\*(C'\fR and
254 they must be runnable, or installation will fail. \f(CW\*(C`\-force\-arch\*(C'\fR is a
255 synonym.
256 .IP "\fB\-help\fR, \fB\-\-help\fR, \fB\-?\fR" 4
257 .IX Item "-help, --help, -?"
258 Display this help and exit. (This help is also on the web at
259 <https://tug.org/texlive/doc/install\-tl.html>). Sometimes the \f(CW\*(C`perldoc\*(C'\fR
260 and/or \f(CW\*(C`PAGER\*(C'\fR programs on the system have problems, possibly resulting
261 in control characters being literally output. This can\*(Aqt always be
262 detected, but you can set the \f(CW\*(C`NOPERLDOC\*(C'\fR environment variable and
263 \&\f(CW\*(C`perldoc\*(C'\fR will not be used.
264 .IP \fB\-in\-place\fR 4
265 .IX Item "-in-place"
266 This is a quick\-and\-dirty installation option in case you already have
267 an rsync or svn checkout of TeX Live. It will use the checkout as\-is
268 and will just do the necessary post\-install. Be warned that the file
269 \&\f(CW\*(C`tlpkg/texlive.tlpdb\*(C'\fR may be rewritten, that removal has to be done
270 manually, and that the only realistic way to maintain this installation
271 is to redo it from time to time. This option is not available via the
272 installer interfaces. USE AT YOUR OWN RISK.
273 .IP "\fB\-init\-from\-profile\fR \fIprofile_file\fR" 4
274 .IX Item "-init-from-profile profile_file"
275 Similar to \fB\-profile\fR (see "PROFILES" below), but only initializes
276 the installation configuration from \fIprofile_file\fR and then starts a
277 normal interactive session. Environment variables are not ignored.
278 .IP "\fB\-logfile\fR \fIfile\fR" 4
279 .IX Item "-logfile file"
280 Write both all messages (informational, debugging, warnings) to \fIfile\fR,
281 in addition to standard output or standard error.
282 .Sp
283 If this option is not given, the installer will create a log file
284 in the root of the writable installation tree,
285 for example, \f(CW\*(C`/usr/local/texlive/YYYY/install\-tl.log\*(C'\fR for the \fIYYYY\fR
286 release.
287 .IP \fB\-no\-cls\fR 4
288 .IX Item "-no-cls"
289 For the text mode installer only: do not clear the screen when entering
290 a new menu. For debugging.
291 .IP \fB\-no\-continue\fR 4
292 .IX Item "-no-continue"
293 Quit early on installation failure of a non\-core package.
294 .Sp
295 By default, a few core packages are installed first; then, a failed
296 installation of any other (non\-core) package is noted, but does not stop
297 the installation. Any such failed packages are retried, once.
298 .Sp
299 If the retry also fails, by default the installer proceeds to completion
300 anyway, with the idea that it was a transient network problem and
301 reinstallation will succeed later. If this option is specified, and the
302 retry fails, the installer aborts.
303 .IP \fB\-no\-doc\-install\fR 4
304 .IX Item "-no-doc-install"
305 .PD 0
306 .IP \fB\-no\-src\-install\fR 4
307 .IX Item "-no-src-install"
308 .PD
309 Do not install the documentation resp. source package files, both for
310 the immediate installation and for future updates. After installation,
311 inclusion of the doc/src files can be re\-enabled via \f(CW\*(C`tlmgr\*(C'\fR:
312 .Sp
313 .Vb 2
314 \& tlmgr option docfiles 1
315 \& tlmgr option srcfiles 1
316 .Ve
317 .Sp
318 If you later find that you want the doc/src files for a package that has
319 been installed without them, you can get them like this (using the
320 \&\f(CW\*(C`fontspec\*(C'\fR package as the example):
321 .Sp
322 .Vb 1
323 \& tlmgr install \-\-reinstall \-\-with\-doc \-\-with\-src fontspec
324 .Ve
325 .Sp
326 The source files mentioned here are those relating to TeX packages, such
327 as \f(CW\*(C`.dtx\*(C'\fR files. The sources that are compiled to make the binaries are
328 available separately: see <https://tug.org/texlive/svn/>.
329 .IP \fB\-no\-installation\fR 4
330 .IX Item "-no-installation"
331 Do not perform any installation. This is for debugging the
332 initialization and setup routines without touching the disk.
333 .IP \fB\-no\-interaction\fR 4
334 .IX Item "-no-interaction"
335 Do not enter the interactive menu; immediately perform the installation
336 after initialization and option parsing. Also omit the check for a
337 previous installation and asking about importing previous settings.
338 .IP \fB\-no\-persistent\-downloads\fR 4
339 .IX Item "-no-persistent-downloads"
340 .PD 0
341 .IP \fB\-persistent\-downloads\fR 4
342 .IX Item "-persistent-downloads"
343 .PD
344 For network installs, activating this option makes the installer try to
345 set up a persistent connection using the \f(CW\*(C`LWP\*(C'\fR Perl module. This
346 opens only one connection between your computer and the server per
347 session and reuses it, instead of initiating a new download for each
348 package, which typically yields a significant speed\-up.
349 .Sp
350 This option is turned on by default, and the installation program will
351 fall back to using \f(CW\*(C`wget\*(C'\fR if this is not possible. To disable usage of
352 LWP and persistent connections, use \f(CW\*(C`\-no\-persistent\-downloads\*(C'\fR.
353 .IP \fB\-no\-verify\-downloads\fR 4
354 .IX Item "-no-verify-downloads"
355 By default, if a GnuPG \f(CW\*(C`gpg\*(C'\fR binary is found in PATH, downloads are
356 verified against a cryptographic signature. This option disables such
357 verification. The full description is in the Crytographic Verification
358 section of the \f(CW\*(C`tlmgr\*(C'\fR documentation, e.g.,
359 <https://tug.org/texlive/doc/tlmgr.html#CRYPTOGRAPHIC\-VERIFICATION>
360 .IP \fB\-non\-admin\fR 4
361 .IX Item "-non-admin"
362 For Windows only: configure for the current user, not for all users.
363 .ie n .IP "\fB\-paper\fR ""a4""\fB|\fR""letter""" 4
364 .el .IP "\fB\-paper\fR \f(CWa4\fR\fB|\fR\f(CWletter\fR" 4
365 .IX Item "-paper a4|letter"
366 Set the default paper size for all TeX Live programs, as specified.
367 The default is \f(CW\*(C`a4\*(C'\fR. The paper size can be set after installation with
368 the \f(CW\*(C`tlmgr paper\*(C'\fR command.
369 .IP \fB\-portable\fR 4
370 .IX Item "-portable"
371 Install for portable use, e.g., on a USB stick. See the
372 \&\f(CW\*(C`instopt_portable\*(C'\fR description below for details.
373 .IP \fB\-print\-platform\fR 4
374 .IX Item "-print-platform"
375 Print the TeX Live identifier for the detected platform
376 (hardware/operating system) combination to standard output, and exit.
377 \&\f(CW\*(C`\-print\-arch\*(C'\fR is a synonym.
378 .IP "\fB\-profile\fR \fIprofile_file\fR" 4
379 .IX Item "-profile profile_file"
380 Load \fIprofile_file\fR and do the installation with no user interaction,
381 that is, a batch (unattended) install. Environment variables are
382 ignored. See "PROFILES" below.
383 .IP \fB\-q\fR 4
384 .IX Item "-q"
385 Omit normal informational messages.
386 .IP "\fB\-scheme\fR \fIscheme\fR" 4
387 .IX Item "-scheme scheme"
388 Schemes are the highest level of package grouping in TeX Live; the
389 default is to use the \f(CW\*(C`full\*(C'\fR scheme, which includes everything. This
390 option overrides that default. The \fIscheme\fR argument value may
391 optionally have a prefix \f(CW\*(C`scheme\-\*(C'\fR. The list of supported scheme names
392 depends on what your package repository provides; see the interactive
393 menu list.
394 .IP \fB\-strict\fR 4
395 .IX Item "-strict"
396 .PD 0
397 .IP \fB\-no\-strict\fR 4
398 .IX Item "-no-strict"
399 .PD
400 By default, \f(CW\*(C`install\-tl\*(C'\fR runs to completion even if one of the
401 post\-installation commands fail, such as \f(CW\*(C`fmtutil\-sys\*(C'\fR or
402 \&\f(CW\*(C`updmap\-sys\*(C'\fR. This is to avoid necessarily downloading the entire
403 distribution again, since usually the problems can be fixed afterwards
404 without too much trouble (warnings are summarized at the end of the
405 \&\f(CW\*(C`install\-tl\*(C'\fR output, and see the log file for the exact error messages
406 and other information), and TeX may well be functional. A future \f(CW\*(C`tlmgr
407 update\*(C'\fR run will almost certainly fail, however.
408 .Sp
409 If the \fB\-strict\fR option is given, \f(CW\*(C`install\-tl\*(C'\fR quits right away if any
410 post\-installation command fails. This can be useful for testing, if
411 re\-downloading is not a problem, etc.
412 .IP "\fB\-texdir\fR \fIdir\fR" 4
413 .IX Item "-texdir dir"
414 Specify the system installation directory; the default is
415 \&\f(CW\*(C`/usr/local/texlive/YYYY\*(C'\fR for release YYYY. Specifying this option also
416 causes the \f(CW\*(C`TEXMFLOCAL\*(C'\fR, \f(CW\*(C`TEXMFSYSCONFIG\*(C'\fR, and \f(CW\*(C`TEXMFSYSVAR\*(C'\fR
417 directories to be set as subdirectories of \fIdir\fR, so they don\*(Aqt have to
418 be set individually.
419 .Sp
420 There is a brief summary of these directories trees at "DIRECTORY
421 TREES" below; for details on the trees set up by default, and their
422 intended usage, see the main TeX Live documentation at
423 <https://tug.org/texlive/doc>.
424 .IP "\fB\-texuserdir\fR \fIdir\fR" 4
425 .IX Item "-texuserdir dir"
426 Specify the user installation directory; the default is
427 \&\f(CW\*(C`~/.texliveYYYY\*(C'\fR (except on Macs, where there is no leading dot).
428 Specifying this also causes the \f(CW\*(C`TEXMFHOME\*(C'\fR, \f(CW\*(C`TEXMFCONFIG\*(C'\fR, and
429 \&\f(CW\*(C`TEXMFVAR\*(C'\fR directories to be set as subdirectories of \fIdir\fR.
430 .IP "\fB\-texmflocal\fR \fIdir\fR" 4
431 .IX Item "-texmflocal dir"
432 Specify the \f(CW\*(C`TEXMFLOCAL\*(C'\fR directory; the default is
433 \&\f(CW\*(C`/usr/local/texlive/texmf\-local\*(C'\fR, that is, one level up from the main
434 installation. This is so locally\-installed packages can be easily used
435 across releases, which is usually desirable. Specifying the \f(CW\*(C`\-texdir\*(C'\fR
436 option changes this, putting \f(CW\*(C`TEXMFLOCAL\*(C'\fR under the main tree. The
437 \&\f(CW\*(C`\-texmflocal\*(C'\fR option can be used to specify an explicit directory.
438 .Sp
439 Anything installed here must follow the TeX directory structure (TDS),
440 e.g., \f(CW\*(C`TEXMFHOME/tex/latex/mypkg/mypkg.sty\*(C'\fR. TDS reference:
441 <https://tug.org/tds>.
442 .IP "\fB\-texmfhome\fR \fIdir\fR" 4
443 .IX Item "-texmfhome dir"
444 Specify the \f(CW\*(C`TEXMFHOME\*(C'\fR directory; the default is \f(CW\*(C`~/texmf\*(C'\fR, except on
445 Macs, where it is \f(CW\*(C`~/Library/texmf\*(C'\fR. Analogously to \f(CW\*(C`TEXMFLOCAL\*(C'\fR, the
446 \&\f(CW\*(C`\-texuserdir\*(C'\fR option changes this default.
447 .Sp
448 Also as with \f(CW\*(C`TEXMFLOCAL\*(C'\fR, anything installed here must follow the TDS.
449 .IP "\fB\-texmfsysconfig\fR \fIdir\fR" 4
450 .IX Item "-texmfsysconfig dir"
451 .PD 0
452 .IP "\fB\-texmfsysvar\fR \fIdir\fR" 4
453 .IX Item "-texmfsysvar dir"
454 .PD
455 Specify the \f(CW\*(C`TEXMFSYSCONFIG\*(C'\fR and \f(CW\*(C`TEXMFSYSVAR\*(C'\fR system directories.
456 .IP "\fB\-texmfconfig\fR \fIdir\fR" 4
457 .IX Item "-texmfconfig dir"
458 .PD 0
459 .IP "\fB\-texmfvar\fR \fIdir\fR" 4
460 .IX Item "-texmfvar dir"
461 .PD
462 Specify the \f(CW\*(C`TEXMFCONFIG\*(C'\fR and \f(CW\*(C`TEXMFVAR\*(C'\fR user directories.
463 The defaults are \f(CW\*(C`~/.texliveYYYY/texmf\-{config,var}\*(C'\fR, except on Macs,
464 where the leading dot is omitted (\f(CW\*(C`~/texliveYYYY/...\*(C'\fR).
465 .IP \fB\-v\fR 4
466 .IX Item "-v"
467 Include verbose debugging messages; repeat for maximum debugging: \f(CW\*(C`\-v
468 \&\-v\*(C'\fR. (Further repeats are accepted but ignored.)
469 .IP "\fB\-version\fR, \fB\-\-version\fR" 4
470 .IX Item "-version, --version"
471 Output version information and exit. If \f(CW\*(C`\-v\*(C'\fR is also given, the
472 versions of the TeX Live modules used are also reported.
473 .SH PROFILES
474 .IX Header "PROFILES"
475 A \fIprofile\fR file normally contains all the values needed to perform an
476 installation. After a normal installation has finished, a profile for
477 that exact installation is written to the file \f(CW\*(C`tlpkg/texlive.profile\*(C'\fR.
478 In addition, from the text menu one can select \f(CW\*(C`P\*(C'\fR to save the current
479 setup as a profile at any time. These are small text files; feel free to
480 peruse and edit them according to your needs.
481 .PP
482 Such a profile file can be given as the argument to \f(CW\*(C`\-profile\*(C'\fR, for
483 example to redo the exact same installation on a different system.
484 Alternatively, you can use a custom profile, most easily created by
485 starting from a generated one and changing values. An empty profile
486 file will cause the installer to use the defaults.
487 .PP
488 As mentioned above, the installer only supports selection by scheme and
489 collections, not individual packages, so packages cannot be specified in
490 profile files either. Use \f(CW\*(C`tlmgr\*(C'\fR to work at the package level.
491 .PP
492 Within a profile file, each line consists of
493 .PP
494 \&\fIvariable\fR [\fIvalue\fR]
495 .PP
496 except for comment lines starting with \f(CW\*(C`#\*(C'\fR. The possible variable
497 names are listed below. Values, when present, are either \f(CW0\fR or \f(CW1\fR
498 for booleans, or strings (which must be specified without any quote
499 characters). Leading whitespace is ignored.
500 .PP
501 If the variable \f(CW\*(C`selected_scheme\*(C'\fR is defined and \fIno\fR collection
502 variables at all are defined, then the collections required by the
503 specified scheme (which might change over time) are installed, without
504 explicitly listing them. This eases maintenance of profile files. If any
505 collections are specified in a profile, though, then the scheme is
506 ignored and all desired collections must be given explicitly.
507 .PP
508 For example, a line
509 .PP
510 .Vb 1
511 \& selected_scheme scheme\-small
512 .Ve
513 .PP
514 along with definitions for the installation directories (given below
515 under "path options") suffices to install the "small" scheme with all
516 default options. The schemes are described in the \f(CW\*(C`S\*(C'\fR menu in the
517 text installer, or equivalent.
518 .PP
519 In addition to \f(CW\*(C`selected_scheme\*(C'\fR, here are the other variable names
520 supported in a profile:
521 .PP
522 \&\fBcollection options\fR (prefix \f(CW\*(C`collection\-\*(C'\fR)
523 .PP
524 Collections are specified with a variable name with the prefix
525 \&\f(CW\*(C`collection\-\*(C'\fR followed by a collection name; there is no value. For
526 instance, \f(CW\*(C`collection\-basic\*(C'\fR. The collections are described in the
527 \&\f(CW\*(C`C\*(C'\fR menu.
528 .PP
529 Schemes and collections (and packages) are ultimately defined by the
530 files in the \f(CW\*(C`tlpkg/tlpsrc/\*(C'\fR source directory.
531 .PP
532 \&\fBpath options\fR
533 .PP
534 It is best to define all of these, even though they may not be used in a
535 given installation, so as to avoid unintentionally getting a default
536 value that could cause problems later.
537 .PP
538 .Vb 7
539 \& TEXDIR
540 \& TEXMFLOCAL
541 \& TEXMFSYSCONFIG
542 \& TEXMFSYSVAR
543 \& TEXMFCONFIG
544 \& TEXMFVAR
545 \& TEXMFHOME
546 .Ve
547 .PP
548 \&\fBinstaller options\fR (prefix \f(CW\*(C`instopt_\*(C'\fR)
549 .ie n .IP """instopt_adjustpath"" (default 0 on Unix, 1 on Windows)" 4
550 .el .IP "\f(CWinstopt_adjustpath\fR (default 0 on Unix, 1 on Windows)" 4
551 .IX Item "instopt_adjustpath (default 0 on Unix, 1 on Windows)"
552 Adjust \f(CW\*(C`PATH\*(C'\fR environment variable.
553 .ie n .IP """instopt_adjustrepo"" (default 1)" 4
554 .el .IP "\f(CWinstopt_adjustrepo\fR (default 1)" 4
555 .IX Item "instopt_adjustrepo (default 1)"
556 Set remote repository to a multiplexed CTAN mirror after installation;
557 see \f(CW\*(C`\-repository\*(C'\fR above.
558 .ie n .IP """instopt_letter"" (default 0)" 4
559 .el .IP "\f(CWinstopt_letter\fR (default 0)" 4
560 .IX Item "instopt_letter (default 0)"
561 Set letter size paper as the default, instead of a4.
562 .ie n .IP """instopt_portable"" (default 0)" 4
563 .el .IP "\f(CWinstopt_portable\fR (default 0)" 4
564 .IX Item "instopt_portable (default 0)"
565 Install for portable use, e.g., on a USB stick, without touching the
566 host system. Specifically, this forces the user directories
567 \&\f(CW\*(C`TEXMFHOME\*(C'\fR, \f(CW\*(C`TEXMFCONFIG\*(C'\fR, \f(CW\*(C`TEXMFVAR\*(C'\fR to be identical to the system
568 directories \f(CW\*(C`TEXMFLOCAL\*(C'\fR, \f(CW\*(C`TEXMFSYSCONFIG\*(C'\fR, \f(CW\*(C`TEXMFSYSVAR\*(C'\fR,
569 respectively (regardless of other options and environment variable.)
570 .Sp
571 In addition, on Windows, it disables the desktop integration, path
572 adjustment, and file associations actions usually performed.
573 .ie n .IP """instopt_write18_restricted"" (default 1)" 4
574 .el .IP "\f(CWinstopt_write18_restricted\fR (default 1)" 4
575 .IX Item "instopt_write18_restricted (default 1)"
576 Enable \f(CW\*(C`\ewrite18\*(C'\fR for a restricted set of programs.
577 .PP
578 \&\fBtlpdb options\fR (prefix \f(CW\*(C`tlpdbopt_\*(C'\fR)
579 .PP
580 The definitive list is given in \f(CW\*(C`tlpkg/TeXLive/TLConfig.pm\*(C'\fR, in the hash
581 \&\f(CW%TeXLive::TLConfig::TLPDBOptions\fR, together with explanations. All
582 items given there \fIexcept\fR for \f(CW\*(C`tlpdbopt_location\*(C'\fR can be specified.
583 Here is the current list:
584 .PP
585 .Vb 10
586 \& tlpdbopt_autobackup
587 \& tlpdbopt_backupdir
588 \& tlpdbopt_create_formats
589 \& tlpdbopt_desktop_integration
590 \& tlpdbopt_file_assocs
591 \& tlpdbopt_generate_updmap
592 \& tlpdbopt_install_docfiles
593 \& tlpdbopt_install_srcfiles
594 \& tlpdbopt_post_code
595 \& tlpdbopt_sys_bin
596 \& tlpdbopt_sys_info
597 \& tlpdbopt_sys_man
598 \& tlpdbopt_w32_multi_user
599 .Ve
600 .PP
601 \&\fBplatform options\fR (prefix \f(CW\*(C`binary_\*(C'\fR)
602 .PP
603 For each supported platform in TeX Live (directories under \f(CW\*(C`bin/\*(C'\fR), the
604 variable \f(CW\*(C`binary_\*(C'\fR\fIPLATFORM\fR can be set with value 1. For example:
605 .PP
606 .Vb 1
607 \& binary_x86_64\-linux 1
608 .Ve
609 .PP
610 If no \f(CW\*(C`binary_\*(C'\fR settings are made, the default is whatever the
611 current machine is running.
612 .PP
613 In releases before 2017, many profile variables had different
614 names (not documented here; see the \f(CW\*(C`install\-tl\*(C'\fR source). They are
615 accepted and transformed to the names given above. When a profile is
616 written, the names above are always used.
617 .PP
618 For more details on all of the above options, consult the TeX Live
619 installation manual, linked from <https://tug.org/texlive/doc>.
620 .SH "ENVIRONMENT VARIABLES"
621 .IX Header "ENVIRONMENT VARIABLES"
622 For ease in scripting and debugging, \f(CW\*(C`install\-tl\*(C'\fR looks for the
623 following environment variables. They are not of interest for normal
624 user installations.
625 .ie n .IP """NOPERLDOC""" 4
626 .el .IP \f(CWNOPERLDOC\fR 4
627 .IX Item "NOPERLDOC"
628 Don\*(Aqt try to run the \f(CW\*(C`\-\-help\*(C'\fR message through \f(CW\*(C`perldoc\*(C'\fR.
629 .ie n .IP """TEXLIVE_DOWNLOADER""" 4
630 .el .IP \f(CWTEXLIVE_DOWNLOADER\fR 4
631 .IX Item "TEXLIVE_DOWNLOADER"
632 .PD 0
633 .ie n .IP """TL_DOWNLOAD_PROGRAM""" 4
634 .el .IP \f(CWTL_DOWNLOAD_PROGRAM\fR 4
635 .IX Item "TL_DOWNLOAD_PROGRAM"
636 .ie n .IP """TL_DOWNLOAD_ARGS""" 4
637 .el .IP \f(CWTL_DOWNLOAD_ARGS\fR 4
638 .IX Item "TL_DOWNLOAD_ARGS"
639 .ie n .IP """TEXLIVE_PREFER_OWN""" 4
640 .el .IP \f(CWTEXLIVE_PREFER_OWN\fR 4
641 .IX Item "TEXLIVE_PREFER_OWN"
642 .PD
643 These override the normal choice of the download and other utility
644 programs; see the \f(CW\*(C`tlmgr\*(C'\fR documentation, e.g.,
645 <https://tug.org/texlive/doc/tlmgr.html#ENVIRONMENT\-VARIABLES>.
646 .ie n .IP """TEXLIVE_INSTALL_ENV_NOCHECK""" 4
647 .el .IP \f(CWTEXLIVE_INSTALL_ENV_NOCHECK\fR 4
648 .IX Item "TEXLIVE_INSTALL_ENV_NOCHECK"
649 Omit the check for environment variables containing the string \f(CW\*(C`tex\*(C'\fR.
650 People developing TeX\-related software are likely to have many such
651 variables.
652 .ie n .IP """TEXLIVE_INSTALL_NO_CONTEXT_CACHE""" 4
653 .el .IP \f(CWTEXLIVE_INSTALL_NO_CONTEXT_CACHE\fR 4
654 .IX Item "TEXLIVE_INSTALL_NO_CONTEXT_CACHE"
655 Omit creating the ConTeXt cache. This is useful for redistributors.
656 .ie n .IP """TEXLIVE_INSTALL_NO_DISKCHECK""" 4
657 .el .IP \f(CWTEXLIVE_INSTALL_NO_DISKCHECK\fR 4
658 .IX Item "TEXLIVE_INSTALL_NO_DISKCHECK"
659 If set to 1, omit free disk space check. By default, if a
660 POSIX\-compliant \f(CW\*(C`df\*(C'\fR program (supporting \f(CW\*(C`\-Pk\*(C'\fR) is available, the
661 installer checks for available disk space in the selected installation
662 location, and will abort installation if there is insufficient disk
663 space, plus a margin of 100MB. An equivalent check is made on Windows
664 (not involving \f(CW\*(C`df\*(C'\fR).
665 .ie n .IP """TEXLIVE_INSTALL_NO_RESUME""" 4
666 .el .IP \f(CWTEXLIVE_INSTALL_NO_RESUME\fR 4
667 .IX Item "TEXLIVE_INSTALL_NO_RESUME"
668 Omit check for installing on top of a previous installation and then
669 asking about importing previous settings.
670 .ie n .IP """TEXLIVE_INSTALL_NO_WELCOME""" 4
671 .el .IP \f(CWTEXLIVE_INSTALL_NO_WELCOME\fR 4
672 .IX Item "TEXLIVE_INSTALL_NO_WELCOME"
673 Omit printing the welcome message after successful installation, e.g.,
674 when testing.
675 .ie n .IP """TEXLIVE_INSTALL_PAPER""" 4
676 .el .IP \f(CWTEXLIVE_INSTALL_PAPER\fR 4
677 .IX Item "TEXLIVE_INSTALL_PAPER"
678 Set the default paper size for all relevant programs; must be either
679 \&\f(CW\*(C`letter\*(C'\fR or \f(CW\*(C`a4\*(C'\fR. The default is \f(CW\*(C`a4\*(C'\fR.
680 .ie n .IP """TEXLIVE_INSTALL_PREFIX""" 4
681 .el .IP \f(CWTEXLIVE_INSTALL_PREFIX\fR 4
682 .IX Item "TEXLIVE_INSTALL_PREFIX"
683 .PD 0
684 .ie n .IP """TEXLIVE_INSTALL_TEXMFCONFIG""" 4
685 .el .IP \f(CWTEXLIVE_INSTALL_TEXMFCONFIG\fR 4
686 .IX Item "TEXLIVE_INSTALL_TEXMFCONFIG"
687 .ie n .IP """TEXLIVE_INSTALL_TEXMFVAR""" 4
688 .el .IP \f(CWTEXLIVE_INSTALL_TEXMFVAR\fR 4
689 .IX Item "TEXLIVE_INSTALL_TEXMFVAR"
690 .ie n .IP """TEXLIVE_INSTALL_TEXMFHOME""" 4
691 .el .IP \f(CWTEXLIVE_INSTALL_TEXMFHOME\fR 4
692 .IX Item "TEXLIVE_INSTALL_TEXMFHOME"
693 .ie n .IP """TEXLIVE_INSTALL_TEXMFLOCAL""" 4
694 .el .IP \f(CWTEXLIVE_INSTALL_TEXMFLOCAL\fR 4
695 .IX Item "TEXLIVE_INSTALL_TEXMFLOCAL"
696 .ie n .IP """TEXLIVE_INSTALL_TEXMFSYSCONFIG""" 4
697 .el .IP \f(CWTEXLIVE_INSTALL_TEXMFSYSCONFIG\fR 4
698 .IX Item "TEXLIVE_INSTALL_TEXMFSYSCONFIG"
699 .ie n .IP """TEXLIVE_INSTALL_TEXMFSYSVAR""" 4
700 .el .IP \f(CWTEXLIVE_INSTALL_TEXMFSYSVAR\fR 4
701 .IX Item "TEXLIVE_INSTALL_TEXMFSYSVAR"
702 .PD
703 Specify the respective directories. \f(CW\*(C`TEXLIVE_INSTALL_PREFIX\*(C'\fR defaults
704 to \f(CW\*(C`/usr/local/texlive\*(C'\fR. All the defaults can be seen by running the
705 installer interactively and then typing \f(CW\*(C`D\*(C'\fR for the directory menu.
706 .Sp
707 The various command line options for specifying directories override
708 these environment variables; since specifying both is usually
709 accidental, a warning is given if the values are different.
710 .SH "DIRECTORY TREES"
711 .IX Header "DIRECTORY TREES"
712 There are a plethora of ways to specify the plethora of directory trees
713 used by TeX Live. By far the simplest, and recommended, approach is not
714 to change anything. The defaults suffice for the vast majority of
715 installations.
716 .PP
717 But, for the sake of explanation, here is a table of the trees and the
718 command line options that change them. The first group of three are
719 system directories, and the second group of three are user directories;
720 the two groups are quite analogous.
721 .PP
722 .Vb 11
723 \& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
724 \& | tree | default | group change | single change |
725 \& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
726 \& | TEXMFLOCAL | /usr/local/texlive/texmf\-local | \-\-texdir | \-\-texmflocal |
727 \& | TEXMFSYSVAR | /usr/local/texlive/YYYY/texmf\-var | \-\-texdir | \-\-texmfsysvar |
728 \& | TEXMFSYSCONFIG | /usr/local/texlive/YYYY/texmf\-config | \-\-texdir | \-\-texmfsysconfig |
729 \& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
730 \& | TEXMFHOME | ~/texmf | \-\-texuserdir | \-\-texmfhome |
731 \& | TEXMFVAR | ~/.texliveYYYY/texmf\-var | \-\-texuserdir | \-\-texmfvar |
732 \& | TEXMFCONFIG | ~/.texliveYYYY/texmf\-config | \-\-texuserdir | \-\-texmfconfig |
733 \& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+
734 .Ve
735 .PP
736 In addition, as mentioned in the previous section, each tree has an
737 environment variable \f(CW\*(C`TEXLIVE_INSTALL_\*(C'\fR\fItree\fR which overrides the
738 default; command line and profile settings both override environment
739 variable settings.
740 .PP
741 The defaults vary slightly on Macs, as explained above in "OPTIONS".
742 .PP
743 For the user trees, the default value uses \f(CW\*(C`~\*(C'\fR, and this is left as a
744 literal \f(CW\*(C`~\*(C'\fR in \f(CW\*(C`texmf.cnf\*(C'\fR. That way, each user can have their own
745 \&\f(CW\*(C`TEXMFHOME\*(C'\fR, etc., as intended. On the other hand, for the system
746 trees, if \f(CW\*(C`~\*(C'\fR is used during the installation, this is assumed to
747 simply be a typing shorthand, and the expanded home directory is written
748 in \f(CW\*(C`texmf.cnf\*(C'\fR, since it doesn\*(Aqt make sense to have user\-specific
749 system directories.
750 .PP
751 For more on the directory trees and their intended usage, see the main
752 TeX Live documentation at <https://tug.org/texlive/doc>.
753 .SH BUGS
754 .IX Header "BUGS"
755 The \f(CW\*(C`install\-tl\*(C'\fR script copies itself into the installed tree.
756 Usually, it can be run from there, using the installed tree as the
757 source for another installation. Occasionally, however, there may be
758 incompatibilities in the code of the new \f(CW\*(C`install\-tl\*(C'\fR and the
759 infrastructure, resulting in (probably) inscrutable Perl errors. The
760 way forward is to run \f(CW\*(C`install\-tl\*(C'\fR out of the installer package
761 (\f(CW\*(C`install\-tl\-unx.tar.gz\*(C'\fR or \f(CW\*(C`install\-tl.zip\*(C'\fR) instead of the
762 installation. Feel free to also report the issue; usually the code
763 can be easily synced up again.
764 .PP
765 By the way, do not try to use \f(CW\*(C`install\-tl\*(C'\fR to adjust options or
766 installed packages in an existing installed tree. Use \f(CW\*(C`tlmgr\*(C'\fR instead.
767 .SH "AUTHORS AND COPYRIGHT"
768 .IX Header "AUTHORS AND COPYRIGHT"
769 This script and its documentation were written for the TeX Live
770 distribution (<https://tug.org/texlive>) and both are licensed under the
771 GNU General Public License Version 2 or later.
772 .PP
773 \&\f(CW$Id:\fR install\-tl 78652 2026\-04\-10 16:18:13Z karl $