install-tl(1) User Contributed Perl Documentation install-tl(1)
NAME
install-tl - TeX Live cross-platform installer
SYNOPSIS
install-tl [option]...
install-tl-windows.bat [option]...
DESCRIPTION
This installer creates a runnable TeX Live installation from various
media, including over the network, from local hard disk, a DVD, etc.
The installer works on all platforms supported by TeX Live. For
information on initially downloading TeX Live, see
<https://tug.org/texlive/acquire.html>.
The basic idea of TeX Live installation is for you to choose one of the
top-level schemes, each of which is defined as a different set of
collections and packages, where a collection is a set of packages, and
a package is what contains actual files. Each package is in exactly one
collection, while schemes can contain any combination of packages and
collections.
Within the installer, you can choose a scheme, and further customize
the set of collections to install, but not the set of the packages. To
work at the package level, use "tlmgr" (reference just below) after the
initial installation is complete.
The default is "scheme-full", which installs everything, and this is
highly recommended.
REFERENCES
Post-installation configuration, package updates, and more, are handled
through tlmgr(1), the TeX Live Manager
(<https://tug.org/texlive/tlmgr.html>).
The most up-to-date version of this installer documentation is on the
Internet at <https://tug.org/texlive/doc/install-tl.html>.
For step-by-step instructions, see
<https://tug.org/texlive/quickinstall.html>.
For the full documentation of TeX Live, see
<https://tug.org/texlive/doc>.
EXAMPLES
With no options, "install-tl" drops you into an interactive menu where
essentially all default settings can be changed. With options, you can
initialize the settings in various ways, or perform the installation
without interaction. Some examples:
"install-tl --paper=letter"
Initialize paper size setting. The only values allowed are "letter"
and (the default) "a4".
"install-tl --scheme" scheme
Initialize the installation scheme; the default is "full". For a
list of schemes, see the interactive "S" menu.
"install-tl --no-interaction"
Perform the installation immediately after parsing options, without
entering the interactive menu.
"install-tl --profile" texlive.profile
Install, without interaction, according to the given TL profile
file; see "PROFILES" below. To initialize from the profile and then
enter the interactive menu, add "--init-from-profile".
Full documentation follows.
OPTIONS
As usual, all options can be specified in any order, and with either a
leading "-" or "--". An argument value can be separated from its
option by either a space or "=".
The options relating to customization of the installation can also be
selected in the interactive installation menus (GUI or text).
-gui [[=]module]
-no-gui
If no module is given, starts the Tcl/Tk (see below) GUI installer.
If module is given loads the given installer module. Currently the
following modules are supported:
"text"
The text mode user interface (default on Unix systems,
including Macs). Same as the "-no-gui" option.
"tcl" (or "perltk" or "wizard" or "expert" or nothing)
The Tcl/Tk user interface (default on Windows). It starts with
a small number of configuration options, roughly equivalent to
what the former wizard option offers, but a button "Advanced"
takes you to a screen with roughly the same options as the
former "perltk" interface.
The default GUI requires Tcl/Tk. This was standard on Macs, but has
been removed in the latest macOS releases. It's often already
installed on GNU/Linux, or can be easily installed through a distro
package manager. For Windows, TeX Live provides a Tcl/Tk runtime.
-lang llcode
By default, the Tcl GUI uses the language detection built into
Tcl/Tk. If that fails you can select a different language by giving
this option with a language code (based on ISO 639-1). Currently
supported (but not necessarily completely translated) are: English
(en, default), Czech (cs), German (de), French (fr), Italian (it),
Japanese (ja), Dutch (nl), Polish (pl), Brazilian Portuguese
(pt_BR), Russian (ru), Slovak (sk), Slovenian (sl), Serbian (sr),
Ukrainian (uk), Vietnamese (vi), simplified Chinese (zh_CN), and
traditional Chinese (zh_TW).
-repository url|path
Specify the package repository to be used as the source of the
installation. In short, this can be a directory name or a url using
http(s), ftp, or scp. The documentation for "tlmgr" has the details
(<https://tug.org/texlive/doc/tlmgr.html#OPTIONS>).
For installation, the default is to pick a mirror automatically,
using <https://mirror.ctan.org/systems/texlive/tlnet>; the chosen
mirror is then used for the entire download. You can use the
special argument "ctan" as an abbreviation for this. (See
<https://ctan.org> for more about CTAN and its mirrors.)
After installation is complete, you can use that installation as
the repository for another installation. If you chose to install
less than the full scheme containing all packages, the list of
available schemes will be adjusted accordingly.
-select-repository
This option allows you to choose a particular mirror from the
current list of active CTAN mirrors. This option is supported in
the "text" and "gui" installer modes, and will also offer to
install from local media if available, or from a repository
specified on the command line. It's useful when the (default)
automatic redirection does not choose a good host for you.
-all-options
Normally options not relevant to the current platform are not shown
(e.g., when running on Unix, Windows-specific options are omitted).
Giving this command line option allows configuring such "foreign"
settings.
-custom-bin path
If you have built your own set of TeX Live binaries (e.g., because
precompiled binaries were not provided by TL for your platform),
this option allows you to specify the path to a directory where the
binaries for the current system are present. The installation will
continue as usual, but at the end all files from path are copied
over to "bin/custom/" under your installation directory and this
"bin/custom/" directory is what will be added to the path for the
post-install actions. To install multiple custom binary sets,
manually rename "custom" before doing each.
For more information on custom binaries, see
<https://tug.org/texlive/custom-bin.html>. For general information
on building TeX Live, see <https://tug.org/texlive/build.html>.
-debug-fakenet
Pretend we're doing a network install. This is for the sole purpose
of testing the code to handle broken downloads, via moving package
files aside in a tlnet mirror hierarchy.
-debug-setup-vars
Print final values of directory variables; for more debugging
information on how they were set, also specify "-v".
-debug-translation
In the former Perl/Tk GUI modes, this option reported any missing,
or more likely untranslated, messages to standard error. Not yet
implemented for the Tcl interface. Helpful for translators to see
what remains to be done.
-force-platform platform
Instead of auto-detecting the current platform, use platform.
Binaries for this platform must be present in "bin/"platform"/" and
they must be runnable, or installation will fail. "-force-arch" is
a synonym.
-help, --help, -?
Display this help and exit. (This help is also on the web at
<https://tug.org/texlive/doc/install-tl.html>). Sometimes the
"perldoc" and/or "PAGER" programs on the system have problems,
possibly resulting in control characters being literally output.
This can't always be detected, but you can set the "NOPERLDOC"
environment variable and "perldoc" will not be used.
-in-place
This is a quick-and-dirty installation option in case you already
have an rsync or svn checkout of TeX Live. It will use the
checkout as-is and will just do the necessary post-install. Be
warned that the file "tlpkg/texlive.tlpdb" may be rewritten, that
removal has to be done manually, and that the only realistic way to
maintain this installation is to redo it from time to time. This
option is not available via the installer interfaces. USE AT YOUR
OWN RISK.
-init-from-profile profile_file
Similar to -profile (see "PROFILES" below), but only initializes
the installation configuration from profile_file and then starts a
normal interactive session. Environment variables are not ignored.
-logfile file
Write both all messages (informational, debugging, warnings) to
file, in addition to standard output or standard error.
If this option is not given, the installer will create a log file
in the root of the writable installation tree, for example,
"/usr/local/texlive/YYYY/install-tl.log" for the YYYY release.
-no-cls
For the text mode installer only: do not clear the screen when
entering a new menu. For debugging.
-no-continue
Quit early on installation failure of a non-core package.
By default, a few core packages are installed first; then, a failed
installation of any other (non-core) package is noted, but does not
stop the installation. Any such failed packages are retried, once.
If the retry also fails, by default the installer proceeds to
completion anyway, with the idea that it was a transient network
problem and reinstallation will succeed later. If this option is
specified, and the retry fails, the installer aborts.
-no-doc-install
-no-src-install
Do not install the documentation resp. source package files, both
for the immediate installation and for future updates. After
installation, inclusion of the doc/src files can be re-enabled via
"tlmgr":
tlmgr option docfiles 1
tlmgr option srcfiles 1
If you later find that you want the doc/src files for a package
that has been installed without them, you can get them like this
(using the "fontspec" package as the example):
tlmgr install --reinstall --with-doc --with-src fontspec
The source files mentioned here are those relating to TeX packages,
such as ".dtx" files. The sources that are compiled to make the
binaries are available separately: see
<https://tug.org/texlive/svn/>.
-no-installation
Do not perform any installation. This is for debugging the
initialization and setup routines without touching the disk.
-no-interaction
Do not enter the interactive menu; immediately perform the
installation after initialization and option parsing. Also omit the
check for a previous installation and asking about importing
previous settings.
-no-persistent-downloads
-persistent-downloads
For network installs, activating this option makes the installer
try to set up a persistent connection using the "LWP" Perl module.
This opens only one connection between your computer and the server
per session and reuses it, instead of initiating a new download for
each package, which typically yields a significant speed-up.
This option is turned on by default, and the installation program
will fall back to using "wget" if this is not possible. To disable
usage of LWP and persistent connections, use
"-no-persistent-downloads".
-no-verify-downloads
By default, if a GnuPG "gpg" binary is found in PATH, downloads are
verified against a cryptographic signature. This option disables
such verification. The full description is in the Crytographic
Verification section of the "tlmgr" documentation, e.g.,
<https://tug.org/texlive/doc/tlmgr.html#CRYPTOGRAPHIC-VERIFICATION>
-non-admin
For Windows only: configure for the current user, not for all
users.
-paper "a4"|"letter"
Set the default paper size for all TeX Live programs, as specified.
The default is "a4". The paper size can be set after installation
with the "tlmgr paper" command.
-portable
Install for portable use, e.g., on a USB stick. See the
"instopt_portable" description below for details.
-print-platform
Print the TeX Live identifier for the detected platform
(hardware/operating system) combination to standard output, and
exit. "-print-arch" is a synonym.
-profile profile_file
Load profile_file and do the installation with no user interaction,
that is, a batch (unattended) install. Environment variables are
ignored. See "PROFILES" below.
-q Omit normal informational messages.
-scheme scheme
Schemes are the highest level of package grouping in TeX Live; the
default is to use the "full" scheme, which includes everything.
This option overrides that default. The scheme argument value may
optionally have a prefix "scheme-". The list of supported scheme
names depends on what your package repository provides; see the
interactive menu list.
-texdir dir
Specify the system installation directory; the default is
"/usr/local/texlive/YYYY" for release YYYY. Specifying this option
also causes the "TEXMFLOCAL", "TEXMFSYSCONFIG", and "TEXMFSYSVAR"
directories to be set as subdirectories of dir, so they don't have
to be set individually.
There is a brief summary of these directories trees at "DIRECTORY
TREES" below; for details on the trees set up by default, and their
intended usage, see the main TeX Live documentation at
<https://tug.org/texlive/doc>.
-texuserdir dir
Specify the user installation directory; the default is
"~/.texliveYYYY" (except on Macs, where there is no leading dot).
Specifying this also causes the "TEXMFHOME", "TEXMFCONFIG", and
"TEXMFVAR" directories to be set as subdirectories of dir.
-texmflocal dir
Specify the "TEXMFLOCAL" directory; the default is
"/usr/local/texlive/texmf-local", that is, one level up from the
main installation. This is so locally-installed packages can be
easily used across releases, which is usually desirable. Specifying
the "-texdir" option changes this, putting "TEXMFLOCAL" under the
main tree. The "-texmflocal" option can be used to specify an
explicit directory.
Anything installed here must follow the TeX directory structure
(TDS), e.g., "TEXMFHOME/tex/latex/mypkg/mypkg.sty". TDS reference:
<https://tug.org/tds>.
-texmfhome dir
Specify the "TEXMFHOME" directory; the default is "~/texmf", except
on Macs, where it is "~/Library/texmf". Analogously to
"TEXMFLOCAL", the "-texuserdir" option changes this default.
Also as with "TEXMFLOCAL", anything installed here must follow the
TDS.
-texmfsysconfig dir
-texmfsysvar dir
Specify the "TEXMFSYSCONFIG" and "TEXMFSYSVAR" system directories.
-texmfconfig dir
-texmfvar dir
Specify the "TEXMFCONFIG" and "TEXMFVAR" user directories. The
defaults are "~/.texliveYYYY/texmf-{config,var}", except on Macs,
where the leading dot is omitted ("~/texliveYYYY/...").
-v Include verbose debugging messages; repeat for maximum debugging:
"-v -v". (Further repeats are accepted but ignored.)
-version, --version
Output version information and exit. If "-v" is also given, the
versions of the TeX Live modules used are also reported.
PROFILES
A profile file normally contains all the values needed to perform an
installation. After a normal installation has finished, a profile for
that exact installation is written to the file "tlpkg/texlive.profile".
In addition, from the text menu one can select "P" to save the current
setup as a profile at any time. These are small text files; feel free
to peruse and edit them according to your needs.
Such a profile file can be given as the argument to "-profile", for
example to redo the exact same installation on a different system.
Alternatively, you can use a custom profile, most easily created by
starting from a generated one and changing values. An empty profile
file will cause the installer to use the defaults.
As mentioned above, the installer only supports selection by scheme and
collections, not individual packages, so packages cannot be specified
in profile files either. Use "tlmgr" to work at the package level.
Within a profile file, each line consists of
variable [value]
except for comment lines starting with "#". The possible variable
names are listed below. Values, when present, are either 0 or 1 for
booleans, or strings (which must be specified without any quote
characters). Leading whitespace is ignored.
If the variable "selected_scheme" is defined and no collection
variables at all are defined, then the collections required by the
specified scheme (which might change over time) are installed, without
explicitly listing them. This eases maintenance of profile files. If
any collections are specified in a profile, though, then the scheme is
ignored and all desired collections must be given explicitly.
For example, a line
selected_scheme scheme-small
along with definitions for the installation directories (given below
under "path options") suffices to install the "small" scheme with all
default options. The schemes are described in the "S" menu in the text
installer, or equivalent.
In addition to "selected_scheme", here are the other variable names
supported in a profile:
collection options (prefix "collection-")
Collections are specified with a variable name with the prefix
"collection-" followed by a collection name; there is no value. For
instance, "collection-basic". The collections are described in the "C"
menu.
Schemes and collections (and packages) are ultimately defined by the
files in the "tlpkg/tlpsrc/" source directory.
path options
It is best to define all of these, even though they may not be used in
a given installation, so as to avoid unintentionally getting a default
value that could cause problems later.
TEXDIR
TEXMFLOCAL
TEXMFSYSCONFIG
TEXMFSYSVAR
TEXMFCONFIG
TEXMFVAR
TEXMFHOME
installer options (prefix "instopt_")
"instopt_adjustpath" (default 0 on Unix, 1 on Windows)
Adjust "PATH" environment variable.
"instopt_adjustrepo" (default 1)
Set remote repository to a multiplexed CTAN mirror after
installation; see "-repository" above.
"instopt_letter" (default 0)
Set letter size paper as the default, instead of a4.
"instopt_portable" (default 0)
Install for portable use, e.g., on a USB stick, without touching
the host system. Specifically, this forces the user directories
"TEXMFHOME", "TEXMFCONFIG", "TEXMFVAR" to be identical to the
system directories "TEXMFLOCAL", "TEXMFSYSCONFIG", "TEXMFSYSVAR",
respectively (regardless of other options and environment
variable.)
In addition, on Windows, it disables the desktop integration, path
adjustment, and file associations actions usually performed.
"instopt_write18_restricted" (default 1)
Enable "\write18" for a restricted set of programs.
tlpdb options (prefix "tlpdbopt_")
The definitive list is given in "tlpkg/TeXLive/TLConfig.pm", in the
hash %TeXLive::TLConfig::TLPDBOptions, together with explanations. All
items given there except for "tlpdbopt_location" can be specified.
Here is the current list:
tlpdbopt_autobackup
tlpdbopt_backupdir
tlpdbopt_create_formats
tlpdbopt_desktop_integration
tlpdbopt_file_assocs
tlpdbopt_generate_updmap
tlpdbopt_install_docfiles
tlpdbopt_install_srcfiles
tlpdbopt_post_code
tlpdbopt_sys_bin
tlpdbopt_sys_info
tlpdbopt_sys_man
tlpdbopt_w32_multi_user
platform options (prefix "binary_")
For each supported platform in TeX Live (directories under "bin/"), the
variable "binary_"PLATFORM can be set with value 1. For example:
binary_x86_64-linux 1
If no "binary_" settings are made, the default is whatever the current
machine is running.
In releases before 2017, many profile variables had different names
(not documented here; see the "install-tl" source). They are accepted
and transformed to the names given above. When a profile is written,
the names above are always used.
For more details on all of the above options, consult the TeX Live
installation manual, linked from <https://tug.org/texlive/doc>.
ENVIRONMENT VARIABLES
For ease in scripting and debugging, "install-tl" looks for the
following environment variables. They are not of interest for normal
user installations.
"NOPERLDOC"
Don't try to run the "--help" message through "perldoc".
"TEXLIVE_DOWNLOADER"
"TL_DOWNLOAD_PROGRAM"
"TL_DOWNLOAD_ARGS"
These override the normal choice of a download program; see the
"tlmgr" documentation, e.g.,
<https://tug.org/texlive/doc/tlmgr.html#ENVIRONMENT-VARIABLES>.
"TEXLIVE_INSTALL_ENV_NOCHECK"
Omit the check for environment variables containing the string
"tex". People developing TeX-related software are likely to have
many such variables.
"TEXLIVE_INSTALL_NO_CONTEXT_CACHE"
Omit creating the ConTeXt cache. This is useful for
redistributors.
"TEXLIVE_INSTALL_NO_DISKCHECK"
If set to 1, omit free disk space check. By default, if a POSIX-
compliant "df" program (supporting "-Pk") is available, the
installer checks for available disk space in the selected
installation location, and will abort installation if there is
insufficient disk space, plus a margin of 100MB. An equivalent
check is made on Windows (not involving "df").
"TEXLIVE_INSTALL_NO_RESUME"
Omit check for installing on top of a previous installation and
then asking about importing previous settings.
"TEXLIVE_INSTALL_NO_WELCOME"
Omit printing the welcome message after successful installation,
e.g., when testing.
"TEXLIVE_INSTALL_PAPER"
Set the default paper size for all relevant programs; must be
either "letter" or "a4". The default is "a4".
"TEXLIVE_INSTALL_PREFIX"
"TEXLIVE_INSTALL_TEXMFCONFIG"
"TEXLIVE_INSTALL_TEXMFVAR"
"TEXLIVE_INSTALL_TEXMFHOME"
"TEXLIVE_INSTALL_TEXMFLOCAL"
"TEXLIVE_INSTALL_TEXMFSYSCONFIG"
"TEXLIVE_INSTALL_TEXMFSYSVAR"
Specify the respective directories. "TEXLIVE_INSTALL_PREFIX"
defaults to "/usr/local/texlive". All the defaults can be seen by
running the installer interactively and then typing "D" for the
directory menu.
The various command line options for specifying directories
override these environment variables; since specifying both is
usually accidental, a warning is given if the values are different.
DIRECTORY TREES
There are a plethora of ways to specify the plethora of directory trees
used by TeX Live. By far the simplest, and recommended, approach is not
to change anything. The defaults suffice for the vast majority of
installations.
But, for the sake of explanation, here is a table of the trees and the
command line options that change them. The first group of three are
system directories, and the second group of three are user directories;
the two groups are quite analogous.
+----------------+--------------------------------------+--------------+------------------+
| tree | default | group change | single change |
+----------------+--------------------------------------+--------------+------------------+
| TEXMFLOCAL | /usr/local/texlive/texmf-local | --texdir | --texmflocal |
| TEXMFSYSVAR | /usr/local/texlive/YYYY/texmf-var | --texdir | --texmfsysvar |
| TEXMFSYSCONFIG | /usr/local/texlive/YYYY/texmf-config | --texdir | --texmfsysconfig |
+----------------+--------------------------------------+--------------+------------------+
| TEXMFHOME | ~/texmf | --texuserdir | --texmfhome |
| TEXMFVAR | ~/.texliveYYYY/texmf-var | --texuserdir | --texmfvar |
| TEXMFCONFIG | ~/.texliveYYYY/texmf-config | --texuserdir | --texmfconfig |
+----------------+--------------------------------------+--------------+------------------+
In addition, as mentioned in the previous section, each tree has an
environment variable "TEXLIVE_INSTALL_"tree which overrides the
default; command line and profile settings both override environment
variable settings.
The defaults vary slightly on Macs, as explained above in "OPTIONS".
For the user trees, the default value uses "~", and this is left as a
literal "~" in "texmf.cnf". That way, each user can have their own
"TEXMFHOME", etc., as intended. On the other hand, for the system
trees, if "~" is used during the installation, this is assumed to
simply be a typing shorthand, and the expanded home directory is
written in "texmf.cnf", since it doesn't make sense to have user-
specific system directories.
For more on the directory trees and their intended usage, see the main
TeX Live documentation at <https://tug.org/texlive/doc>.
BUGS
The "install-tl" script copies itself into the installed tree.
Usually, it can be run from there, using the installed tree as the
source for another installation. Occasionally, however, there may be
incompatibilities in the code of the new "install-tl" and the
infrastructure, resulting in (probably) inscrutable Perl errors. The
way forward is to run "install-tl" out of the installer package
("install-tl-unx.tar.gz" or "install-tl.zip") instead of the
installation. Feel free to also report the issue; usually the code can
be easily synced up again.
By the way, do not try to use "install-tl" to adjust options or
installed packages in an existing installed tree. Use "tlmgr" instead.
AUTHORS AND COPYRIGHT
This script and its documentation were written for the TeX Live
distribution (<https://tug.org/texlive>) and both are licensed under
the GNU General Public License Version 2 or later.
$Id: install-tl 67839 2023-08-07 21:47:31Z preining $
perl v5.38.0 2023-08-07 install-tl(1)
texlive-basic 70568 - Generated Sun Mar 17 09:05:09 CDT 2024