man > INSTALL-TL(1)

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)