1INSTALL-TL(1) User Contributed Perl Documentation INSTALL-TL(1)
2
6 install-tl - TeX Live cross-platform installer
7
9 install-tl [option]...
10 install-tl-windows.bat [option]...
12
14 This installer creates a runnable TeX Live installation from various
15 media, including over the network, from local hard disk, a DVD, etc.
16 The installer works on all platforms supported by TeX Live. For
17 information on initially downloading TeX Live, see
18 <https://tug.org/texlive/acquire.html>.
19 The basic idea of TeX Live installation is for you to choose one of the
21 top-level schemes, each of which is defined as a different set of
22 collections and packages, where a collection is a set of packages, and
23 a package is what contains actual files. Each package is in exactly one
24 collection, while schemes can contain any combination of packages and
25 collections.
26 Within the installer, you can choose a scheme, and further customize
28 the set of collections to install, but not the set of the packages. To
29 work at the package level, use "tlmgr" (reference just below) after the
30 initial installation is complete.
31 The default is "scheme-full", which installs everything, and this is
33 highly recommended.
34
36 Post-installation configuration, package updates, and more, are handled
37 through tlmgr(1), the TeX Live Manager
38 (<https://tug.org/texlive/tlmgr.html>).
39 The most up-to-date version of this installer documentation is on the
41 Internet at <https://tug.org/texlive/doc/install-tl.html>.
42 For step-by-step instructions, see
44 <https://tug.org/texlive/quickinstall.html>.
45 For the full documentation of TeX Live, see
47 <https://tug.org/texlive/doc>.
48
50 With no options, "install-tl" drops you into an interactive menu where
51 essentially all default settings can be changed. With options, you can
52 initialize the settings in various ways, or perform the installation
53 without interaction. Some examples:
54 "install-tl --paper=letter"
56 Initialize paper size setting. The only values allowed are "letter"
57 and (the default) "a4".
58 "install-tl --scheme" scheme
60 Initialize the installation scheme; the default is "full". For a
61 list of schemes, see the interactive "S" menu.
62 "install-tl --no-interaction"
64 Perform the installation immediately after parsing options, without
65 entering the interactive menu.
66 "install-tl --profile" texlive.profile
68 Install, without interaction, according to the given TL profile
69 file; see "PROFILES" below. To initialize from the profile and then
70 enter the interactive menu, add "--init-from-profile".
71 Full documentation follows.
73
75 As usual, all options can be specified in any order, and with either a
76 leading "-" or "--". An argument value can be separated from its
77 option by either a space or "=".
78 The options relating to customization of the installation can also be
80 selected in the interactive installation menus (GUI or text).
81 -gui [[=]module]
83 -no-gui
84 If no module is given, starts the Tcl/Tk (see below) GUI installer.
85 If module is given loads the given installer module. Currently the
87 following modules are supported:
88 "text"
90 The text mode user interface (default on Unix systems,
91 including Macs). Same as the "-no-gui" option.
92 "tcl" (or "perltk" or "wizard" or "expert" or nothing)
94 The Tcl/Tk user interface (default on Windows). It starts with
95 a small number of configuration options, roughly equivalent to
96 what the former wizard option offers, but a button "Advanced"
97 takes you to a screen with roughly the same options as the
98 former "perltk" interface.
99 The default GUI requires Tcl/Tk. This was standard on Macs, but has
101 been removed in the latest macOS releases. It's often already
102 installed on GNU/Linux, or can be easily installed through a distro
103 package manager. For Windows, TeX Live provides a Tcl/Tk runtime.
104 -lang llcode
106 By default, the Tcl GUI uses the language detection built into
107 Tcl/Tk. If that fails you can select a different language by giving
108 this option with a language code (based on ISO 639-1). Currently
109 supported (but not necessarily completely translated) are: English
110 (en, default), Czech (cs), German (de), French (fr), Italian (it),
111 Japanese (ja), Dutch (nl), Polish (pl), Brazilian Portuguese
112 (pt_BR), Russian (ru), Slovak (sk), Slovenian (sl), Serbian (sr),
113 Ukrainian (uk), Vietnamese (vi), simplified Chinese (zh_CN), and
114 traditional Chinese (zh_TW).
115 -repository url|path
117 Specify the package repository to be used as the source of the
118 installation. In short, this can be a directory name or a url using
119 http(s), ftp, or scp. The documentation for "tlmgr" has the details
120 (<https://tug.org/texlive/doc/tlmgr.html#OPTIONS>).
121 For installation, the default is to pick a mirror automatically,
123 using <https://mirror.ctan.org/systems/texlive/tlnet>; the chosen
124 mirror is then used for the entire download. You can use the
125 special argument "ctan" as an abbreviation for this. (See
126 <https://ctan.org> for more about CTAN and its mirrors.)
127 After installation is complete, you can use that installation as
129 the repository for another installation. If you chose to install
130 less than the full scheme containing all packages, the list of
131 available schemes will be adjusted accordingly.
132 -select-repository
134 This option allows you to choose a particular mirror from the
135 current list of active CTAN mirrors. This option is supported in
136 the "text" and "gui" installer modes, and will also offer to
137 install from local media if available, or from a repository
138 specified on the command line. It's useful when the (default)
139 automatic redirection does not choose a good host for you.
140 -all-options
142 Normally options not relevant to the current platform are not shown
143 (e.g., when running on Unix, Windows-specific options are omitted).
144 Giving this command line option allows configuring such "foreign"
145 settings.
146 -custom-bin path
148 If you have built your own set of TeX Live binaries (e.g., because
149 precompiled binaries were not provided by TL for your platform),
150 this option allows you to specify the path to a directory where the
151 binaries for the current system are present. The installation will
152 continue as usual, but at the end all files from path are copied
153 over to "bin/custom/" under your installation directory and this
154 "bin/custom/" directory is what will be added to the path for the
155 post-install actions. To install multiple custom binary sets,
156 manually rename "custom" before doing each.
157 For more information on custom binaries, see
159 <https://tug.org/texlive/custom-bin.html>. For general information
160 on building TeX Live, see <https://tug.org/texlive/build.html>.
161 -debug-fakenet
163 Pretend we're doing a network install. This is for the sole purpose
164 of testing the code to handle broken downloads, via moving package
165 files aside in a tlnet mirror hierarchy.
166 -debug-setup-vars
168 Print final values of directory variables; for more debugging
169 information on how they were set, also specify "-v".
170 -debug-translation
172 In the former Perl/Tk GUI modes, this option reported any missing,
173 or more likely untranslated, messages to standard error. Not yet
174 implemented for the Tcl interface. Helpful for translators to see
175 what remains to be done.
176 -force-platform platform
178 Instead of auto-detecting the current platform, use platform.
179 Binaries for this platform must be present in "bin/"platform"/" and
180 they must be runnable, or installation will fail. "-force-arch" is
181 a synonym.
182 -help, --help, -?
184 Display this help and exit. (This help is also on the web at
185 <https://tug.org/texlive/doc/install-tl.html>). Sometimes the
186 "perldoc" and/or "PAGER" programs on the system have problems,
187 possibly resulting in control characters being literally output.
188 This can't always be detected, but you can set the "NOPERLDOC"
189 environment variable and "perldoc" will not be used.
190 -in-place
192 This is a quick-and-dirty installation option in case you already
193 have an rsync or svn checkout of TeX Live. It will use the
194 checkout as-is and will just do the necessary post-install. Be
195 warned that the file "tlpkg/texlive.tlpdb" may be rewritten, that
196 removal has to be done manually, and that the only realistic way to
197 maintain this installation is to redo it from time to time. This
198 option is not available via the installer interfaces. USE AT YOUR
199 OWN RISK.
200 -init-from-profile profile_file
202 Similar to -profile (see "PROFILES" below), but only initializes
203 the installation configuration from profile_file and then starts a
204 normal interactive session. Environment variables are not ignored.
205 -logfile file
207 Write both all messages (informational, debugging, warnings) to
208 file, in addition to standard output or standard error.
209 If this option is not given, the installer will create a log file
211 in the root of the writable installation tree, for example,
212 "/usr/local/texlive/YYYY/install-tl.log" for the YYYY release.
213 -no-cls
215 For the text mode installer only: do not clear the screen when
216 entering a new menu. For debugging.
217 -no-continue
219 Quit early on installation failure of a non-core package.
220 By default, a few core packages are installed first; then, a failed
222 installation of any other (non-core) package is noted, but does not
223 stop the installation. Any such failed packages are retried, once.
224 If the retry also fails, by default the installer proceeds to
226 completion anyway, with the idea that it was a transient network
227 problem and reinstallation will succeed later. If this option is
228 specified, and the retry fails, the installer aborts.
229 -no-doc-install
231 -no-src-install
232 Do not install the documentation resp. source package files, both
233 for the immediate installation and for future updates. After
234 installation, inclusion of the doc/src files can be re-enabled via
235 "tlmgr":
236 tlmgr option docfiles 1
238 tlmgr option srcfiles 1
239 If you later find that you want the doc/src files for a package
241 that has been installed without them, you can get them like this
242 (using the "fontspec" package as the example):
243 tlmgr install --reinstall --with-doc --with-src fontspec
245 The source files mentioned here are those relating to TeX packages,
247 such as ".dtx" files. The sources that are compiled to make the
248 binaries are available separately: see
249 <https://tug.org/texlive/svn/>.
250 -no-installation
252 Do not perform any installation. This is for debugging the
253 initialization and setup routines without touching the disk.
254 -no-interaction
256 Do not enter the interactive menu; immediately perform the
257 installation after initialization and option parsing. Also omit the
258 check for a previous installation and asking about importing
259 previous settings.
260 -no-persistent-downloads
262 -persistent-downloads
263 For network installs, activating this option makes the installer
264 try to set up a persistent connection using the "LWP" Perl module.
265 This opens only one connection between your computer and the server
266 per session and reuses it, instead of initiating a new download for
267 each package, which typically yields a significant speed-up.
268 This option is turned on by default, and the installation program
270 will fall back to using "wget" if this is not possible. To disable
271 usage of LWP and persistent connections, use
272 "-no-persistent-downloads".
273 -no-verify-downloads
275 By default, if a GnuPG "gpg" binary is found in PATH, downloads are
276 verified against a cryptographic signature. This option disables
277 such verification. The full description is in the Crytographic
278 Verification section of the "tlmgr" documentation, e.g.,
279 <https://tug.org/texlive/doc/tlmgr.html#CRYPTOGRAPHIC-VERIFICATION>
280 -non-admin
282 For Windows only: configure for the current user, not for all
283 users.
284 -paper "a4"|"letter"
286 Set the default paper size for all TeX Live programs, as specified.
287 The default is "a4". The paper size can be set after installation
288 with the "tlmgr paper" command.
289 -portable
291 Install for portable use, e.g., on a USB stick. See the
292 "instopt_portable" description below for details.
293 -print-platform
295 Print the TeX Live identifier for the detected platform
296 (hardware/operating system) combination to standard output, and
297 exit. "-print-arch" is a synonym.
298 -profile profile_file
300 Load profile_file and do the installation with no user interaction,
301 that is, a batch (unattended) install. Environment variables are
302 ignored. See "PROFILES" below.
303 -q Omit normal informational messages.
305 -scheme scheme
307 Schemes are the highest level of package grouping in TeX Live; the
308 default is to use the "full" scheme, which includes everything.
309 This option overrides that default. The scheme argument value may
310 optionally have a prefix "scheme-". The list of supported scheme
311 names depends on what your package repository provides; see the
312 interactive menu list.
313 -texdir dir
315 Specify the system installation directory; the default is
316 "/usr/local/texlive/YYYY" for release YYYY. Specifying this option
317 also causes the "TEXMFLOCAL", "TEXMFSYSCONFIG", and "TEXMFSYSVAR"
318 directories to be set as subdirectories of dir, so they don't have
319 to be set individually.
320 There is a brief summary of these directories trees at "DIRECTORY
322 TREES" below; for details on the trees set up by default, and their
323 intended usage, see the main TeX Live documentation at
324 <https://tug.org/texlive/doc>.
325 -texuserdir dir
327 Specify the user installation directory; the default is
328 "~/.texliveYYYY" (except on Macs, where there is no leading dot).
329 Specifying this also causes the "TEXMFHOME", "TEXMFCONFIG", and
330 "TEXMFVAR" directories to be set as subdirectories of dir.
331 -texmflocal dir
333 Specify the "TEXMFLOCAL" directory; the default is
334 "/usr/local/texlive/texmf-local", that is, one level up from the
335 main installation. This is so locally-installed packages can be
336 easily used across releases, which is usually desirable. Specifying
337 the "-texdir" option changes this, putting "TEXMFLOCAL" under the
338 main tree. The "-texmflocal" option can be used to specify an
339 explicit directory.
340 Anything installed here must follow the TeX directory structure
342 (TDS), e.g., "TEXMFHOME/tex/latex/mypkg/mypkg.sty". TDS reference:
343 <https://tug.org/tds>.
344 -texmfhome dir
346 Specify the "TEXMFHOME" directory; the default is "~/texmf", except
347 on Macs, where it is "~/Library/texmf". Analogously to
348 "TEXMFLOCAL", the "-texuserdir" option changes this default.
349 Also as with "TEXMFLOCAL", anything installed here must follow the
351 TDS.
352 -texmfsysconfig dir
354 -texmfsysvar dir
355 Specify the "TEXMFSYSCONFIG" and "TEXMFSYSVAR" system directories.
356 -texmfconfig dir
358 -texmfvar dir
359 Specify the "TEXMFCONFIG" and "TEXMFVAR" user directories. The
360 defaults are "~/.texliveYYYY/texmf-{config,var}", except on Macs,
361 where the leading dot is omitted ("~/texliveYYYY/...").
362 -v Include verbose debugging messages; repeat for maximum debugging:
364 "-v -v". (Further repeats are accepted but ignored.)
365 -version, --version
367 Output version information and exit. If "-v" is also given, the
368 versions of the TeX Live modules used are also reported.
369
371 A profile file normally contains all the values needed to perform an
372 installation. After a normal installation has finished, a profile for
373 that exact installation is written to the file "tlpkg/texlive.profile".
374 In addition, from the text menu one can select "P" to save the current
375 setup as a profile at any time. These are small text files; feel free
376 to peruse and edit them according to your needs.
377 Such a profile file can be given as the argument to "-profile", for
379 example to redo the exact same installation on a different system.
380 Alternatively, you can use a custom profile, most easily created by
381 starting from a generated one and changing values. An empty profile
382 file will cause the installer to use the defaults.
383 As mentioned above, the installer only supports selection by scheme and
385 collections, not individual packages, so packages cannot be specified
386 in profile files either. Use "tlmgr" to work at the package level.
387 Within a profile file, each line consists of
389 variable [value]
391 except for comment lines starting with "#". The possible variable
393 names are listed below. Values, when present, are either 0 or 1 for
394 booleans, or strings (which must be specified without any quote
395 characters). Leading whitespace is ignored.
396 If the variable "selected_scheme" is defined and no collection
398 variables at all are defined, then the collections required by the
399 specified scheme (which might change over time) are installed, without
400 explicitly listing them. This eases maintenance of profile files. If
401 any collections are specified in a profile, though, then the scheme is
402 ignored and all desired collections must be given explicitly.
403 For example, a line
405 selected_scheme scheme-small
407 along with definitions for the installation directories (given below
409 under "path options") suffices to install the "small" scheme with all
410 default options. The schemes are described in the "S" menu in the text
411 installer, or equivalent.
412 In addition to "selected_scheme", here are the other variable names
414 supported in a profile:
415 collection options (prefix "collection-")
417 Collections are specified with a variable name with the prefix
419 "collection-" followed by a collection name; there is no value. For
420 instance, "collection-basic". The collections are described in the "C"
421 menu.
422 Schemes and collections (and packages) are ultimately defined by the
424 files in the "tlpkg/tlpsrc/" source directory.
425 path options
427 It is best to define all of these, even though they may not be used in
429 a given installation, so as to avoid unintentionally getting a default
430 value that could cause problems later.
431 TEXDIR
433 TEXMFLOCAL
434 TEXMFSYSCONFIG
435 TEXMFSYSVAR
436 TEXMFCONFIG
437 TEXMFVAR
438 TEXMFHOME
439 installer options (prefix "instopt_")
441 "instopt_adjustpath" (default 0 on Unix, 1 on Windows)
443 Adjust "PATH" environment variable.
444 "instopt_adjustrepo" (default 1)
446 Set remote repository to a multiplexed CTAN mirror after
447 installation; see "-repository" above.
448 "instopt_letter" (default 0)
450 Set letter size paper as the default, instead of a4.
451 "instopt_portable" (default 0)
453 Install for portable use, e.g., on a USB stick, without touching
454 the host system. Specifically, this forces the user directories
455 "TEXMFHOME", "TEXMFCONFIG", "TEXMFVAR" to be identical to the
456 system directories "TEXMFLOCAL", "TEXMFSYSCONFIG", "TEXMFSYSVAR",
457 respectively (regardless of other options and environment
458 variable.)
459 In addition, on Windows, it disables the desktop integration, path
461 adjustment, and file associations actions usually performed.
462 "instopt_write18_restricted" (default 1)
464 Enable "\write18" for a restricted set of programs.
465 tlpdb options (prefix "tlpdbopt_")
467 The definitive list is given in "tlpkg/TeXLive/TLConfig.pm", in the
469 hash %TeXLive::TLConfig::TLPDBOptions, together with explanations. All
470 items given there except for "tlpdbopt_location" can be specified.
471 Here is the current list:
472 tlpdbopt_autobackup
474 tlpdbopt_backupdir
475 tlpdbopt_create_formats
476 tlpdbopt_desktop_integration
477 tlpdbopt_file_assocs
478 tlpdbopt_generate_updmap
479 tlpdbopt_install_docfiles
480 tlpdbopt_install_srcfiles
481 tlpdbopt_post_code
482 tlpdbopt_sys_bin
483 tlpdbopt_sys_info
484 tlpdbopt_sys_man
485 tlpdbopt_w32_multi_user
486 platform options (prefix "binary_")
488 For each supported platform in TeX Live (directories under "bin/"), the
490 variable "binary_"PLATFORM can be set with value 1. For example:
491 binary_x86_64-linux 1
493 If no "binary_" settings are made, the default is whatever the current
495 machine is running.
496 In releases before 2017, many profile variables had different names
498 (not documented here; see the "install-tl" source). They are accepted
499 and transformed to the names given above. When a profile is written,
500 the names above are always used.
501 For more details on all of the above options, consult the TeX Live
503 installation manual, linked from <https://tug.org/texlive/doc>.
504
506 For ease in scripting and debugging, "install-tl" looks for the
507 following environment variables. They are not of interest for normal
508 user installations.
509 "NOPERLDOC"
511 Don't try to run the "--help" message through "perldoc".
512 "TEXLIVE_DOWNLOADER"
514 "TL_DOWNLOAD_PROGRAM"
515 "TL_DOWNLOAD_ARGS"
516 These override the normal choice of a download program; see the
517 "tlmgr" documentation, e.g.,
518 <https://tug.org/texlive/doc/tlmgr.html#ENVIRONMENT-VARIABLES>.
519 "TEXLIVE_INSTALL_ENV_NOCHECK"
521 Omit the check for environment variables containing the string
522 "tex". People developing TeX-related software are likely to have
523 many such variables.
524 "TEXLIVE_INSTALL_NO_CONTEXT_CACHE"
526 Omit creating the ConTeXt cache. This is useful for
527 redistributors.
528 "TEXLIVE_INSTALL_NO_DISKCHECK"
530 If set to 1, omit free disk space check. By default, if a POSIX-
531 compliant "df" program (supporting "-Pk") is available, the
532 installer checks for available disk space in the selected
533 installation location, and will abort installation if there is
534 insufficient disk space, plus a margin of 100MB. An equivalent
535 check is made on Windows (not involving "df").
536 "TEXLIVE_INSTALL_NO_RESUME"
538 Omit check for installing on top of a previous installation and
539 then asking about importing previous settings.
540 "TEXLIVE_INSTALL_NO_WELCOME"
542 Omit printing the welcome message after successful installation,
543 e.g., when testing.
544 "TEXLIVE_INSTALL_PAPER"
546 Set the default paper size for all relevant programs; must be
547 either "letter" or "a4". The default is "a4".
548 "TEXLIVE_INSTALL_PREFIX"
550 "TEXLIVE_INSTALL_TEXMFCONFIG"
551 "TEXLIVE_INSTALL_TEXMFVAR"
552 "TEXLIVE_INSTALL_TEXMFHOME"
553 "TEXLIVE_INSTALL_TEXMFLOCAL"
554 "TEXLIVE_INSTALL_TEXMFSYSCONFIG"
555 "TEXLIVE_INSTALL_TEXMFSYSVAR"
556 Specify the respective directories. "TEXLIVE_INSTALL_PREFIX"
557 defaults to "/usr/local/texlive". All the defaults can be seen by
558 running the installer interactively and then typing "D" for the
559 directory menu.
560 The various command line options for specifying directories
562 override these environment variables; since specifying both is
563 usually accidental, a warning is given if the values are different.
564
566 There are a plethora of ways to specify the plethora of directory trees
567 used by TeX Live. By far the simplest, and recommended, approach is not
568 to change anything. The defaults suffice for the vast majority of
569 installations.
570 But, for the sake of explanation, here is a table of the trees and the
572 command line options that change them. The first group of three are
573 system directories, and the second group of three are user directories;
574 the two groups are quite analogous.
575 +----------------+--------------------------------------+--------------+------------------+
577 | tree | default | group change | single change |
578 +----------------+--------------------------------------+--------------+------------------+
579 | TEXMFLOCAL | /usr/local/texlive/texmf-local | --texdir | --texmflocal |
580 | TEXMFSYSVAR | /usr/local/texlive/YYYY/texmf-var | --texdir | --texmfsysvar |
581 | TEXMFSYSCONFIG | /usr/local/texlive/YYYY/texmf-config | --texdir | --texmfsysconfig |
582 +----------------+--------------------------------------+--------------+------------------+
583 | TEXMFHOME | ~/texmf | --texuserdir | --texmfhome |
584 | TEXMFVAR | ~/.texliveYYYY/texmf-var | --texuserdir | --texmfvar |
585 | TEXMFCONFIG | ~/.texliveYYYY/texmf-config | --texuserdir | --texmfconfig |
586 +----------------+--------------------------------------+--------------+------------------+
587 In addition, as mentioned in the previous section, each tree has an
589 environment variable "TEXLIVE_INSTALL_"tree which overrides the
590 default; command line and profile settings both override environment
591 variable settings.
592 The defaults vary slightly on Macs, as explained above in "OPTIONS".
594 For the user trees, the default value uses "~", and this is left as a
596 literal "~" in "texmf.cnf". That way, each user can have their own
597 "TEXMFHOME", etc., as intended. On the other hand, for the system
598 trees, if "~" is used during the installation, this is assumed to
599 simply be a typing shorthand, and the expanded home directory is
600 written in "texmf.cnf", since it doesn't make sense to have user-
601 specific system directories.
602 For more on the directory trees and their intended usage, see the main
604 TeX Live documentation at <https://tug.org/texlive/doc>.
605
607 The "install-tl" script copies itself into the installed tree.
608 Usually, it can be run from there, using the installed tree as the
609 source for another installation. Occasionally, however, there may be
610 incompatibilities in the code of the new "install-tl" and the
611 infrastructure, resulting in (probably) inscrutable Perl errors. The
612 way forward is to run "install-tl" out of the installer package
613 ("install-tl-unx.tar.gz" or "install-tl.zip") instead of the
614 installation. Feel free to also report the issue; usually the code can
615 be easily synced up again.
616 By the way, do not try to use "install-tl" to adjust options or
618 installed packages in an existing installed tree. Use "tlmgr" instead.
619
621 This script and its documentation were written for the TeX Live
622 distribution (<https://tug.org/texlive>) and both are licensed under
623 the GNU General Public License Version 2 or later.
624 $Id: install-tl 66112 2023-02-23 23:28:27Z karl $
626perl v5.34.0 2023-02-23 INSTALL-TL(1)