INSTALL-TL(1)

📦 version 2026.0, in alpine 3.24

🌸 INSTALL-TL(1) — the TeX Live glow-up zone ✨

okay bestie, so this is the manual page for install-tl (section 1, User Contributed Perl Documentation, iykyk) — the TeX Live cross-platform installer. buckle up, she's a long one 💅

💖 NAME 💖

install-tl — the TeX Live cross-platform installer, aka the girl who sets up your whole TeX Live situation for you 🫶

✨ SYNOPSIS ✨

install-tl [option]...

install-tl-windows.bat [option]...

🦋 DESCRIPTION 🦋

So this installer literally creates a runnable TeX Live installation for you, pulling from all kinds of media — over the network, from a local hard disk, from a DVD, whatever you've got, no cap. And she works on every platform supported by TeX Live, which is giving universal main character energy tbh. For the deets on initially downloading TeX Live, go look at <https://tug.org/texlive/acquire.html> ⭐

The basic idea of TeX Live installation is that you pick one of the top-level schemes, and each scheme is defined as a different set of collections and packages. Break it down: a collection is a set of packages, and a package is what actually contains the files. Every single package lives in exactly one collection — like, no sharing, that's her boundary — while schemes can contain any combination of packages and collections 🌈

Inside the installer you can choose a scheme and then further customize the set of collections to install, but not the set of packages. If you want to work at the package level, use tlmgr (reference right below) once the initial installation is done. periodt.

The default is scheme-full, which installs everything, and honestly this is highly recommended. like, just let her eat 👑

🎀 REFERENCES 🎀

Post-installation configuration, package updates, and more are all handled through tlmgr(1), the TeX Live Manager (<https://tug.org/texlive/tlmgr.html>) 💜

💅 EXAMPLES 💅

With no options at all, install-tl drops you into an interactive menu where basically all the default settings can be changed. With options, you can initialize the settings in various ways, or straight-up perform the installation without interacting with her at all. Some examples, bestie:

install-tl --paper=letter : Initialize the paper size setting. The only values allowed are letter and (the default) a4. that's it, those are the options 🍓

install-tl --scheme scheme : Initialize the installation scheme; the default is full. For a list of schemes, go peek at the interactive S menu 👀

install-tl --no-interaction : Perform the installation immediately after parsing options, without entering the interactive menu. no small talk, just vibes.

install-tl --profile texlive.profile : Install, without interaction, according to the given TL profile file; see PROFILES below. And if you want to initialize from the profile and then enter the interactive menu, just add --init-from-profile ✨

Full documentation follows, so keep reading babe 💖

🔥 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 =. super chill, she's not picky 🤷‍♀️

The options relating to customization of the installation can also be selected in the interactive installation menus (GUI or text). so you've got choices, always 💅

  • -gui [[=]module], -no-gui — If no module is given, starts the Tcl/Tk (see below) GUI installer. If module is given, loads that 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. literally the same thing, don't stress.
    • 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. glow-up screen unlocked ✨

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. so she's got you covered either way 🫶

  • -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). that's a whole world tour, we love to see it 🌍
  • -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. And if you chose to install less than the full scheme containing all packages, the list of available schemes will be adjusted accordingly. smart girl behavior fr fr 💅

  • -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. like when the matchmaker picks wrong, you get to pick yourself 🎀
  • -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. she's being inclusive, we stan 🌈
  • -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. DIY queen energy 👑

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. it's giving method acting 💀
  • -debug-setup-vars — Print final values of directory variables; for more debugging information on how they were set, also specify -v. receipts, printed 📋
  • -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. do it for the translators bestie 🫶
  • -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. no binary, no install, that's the rule ⭐
  • -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. glitchy pager? not her fault, but she's got a workaround 💖
  • -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. 🚨 like genuinely, she said what she said.
  • -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. half-prepped, then you take the wheel 🦋
  • -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. she journals, always 📓

  • -no-cls — For the text mode installer only: do not clear the screen when entering a new menu. For debugging. keep the receipts on screen, periodt 💀
  • -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. so with this flag she's like "nope, we're done here" 🙈

  • -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/>. two whole different things, don't mix them up bestie 🎀

more coming, don't go anywhere 💖

  • -no-installation — literally don't install anything bestie 💅 this is purely for debugging the initialization and setup routines without touching your disk. Zero disk-touching. None. Nada.
  • -no-interaction — skip the interactive menu entirely, just yeet straight into the installation after initialization and option parsing. Also skips the check for a previous installation and the whole "do you wanna import your previous settings" convo. No small talk, just vibes and installing ✨
  • -no-persistent-downloads, -persistent-downloads — for network installs, turning this on makes the installer try to set up a persistent connection using the LWP Perl module. It opens only one connection between your computer and the server per session and reuses it, instead of starting a fresh download for every single package — which typically gives you a significant speed-up 🔥

This option is on by default, and the installation program will fall back to using wget if that's not possible. To disable usage of LWP and persistent connections, use -no-persistent-downloads.

  • -no-verify-downloads — so by default, if a GnuPG gpg binary is found in PATH, downloads get verified against a cryptographic signature. This option disables that verification 🙈 The full description lives in the Crytographic Verification section of the tlmgr documentation, e.g., <https://tug.org/texlive/doc/tlmgr.html#CRYPTOGRAPHIC-VERIFICATION>
  • -non-admin — Windows only, babe: configure for the current user instead of for all users.
  • -paper "a4"|"letter" — set the default paper size for all TeX Live programs, as specified. Default is a4 🎀 The paper size can totally be set after installation with the tlmgr paper command.
  • -portable — install for portable use, like on a USB stick. See the instopt_portable description below for the deets.
  • -print-platform — print the TeX Live identifier for the detected platform (that's your hardware/operating system combo) to standard output, and exit. -print-arch is a synonym, iykyk ✨
  • -profile profile_file — load profile_file and do the installation with no user interaction whatsoever, i.e. a batch (unattended) install 😌 environment variables are ignored. See PROFILES below.
  • -q — omit normal informational messages. Quiet era.
  • -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; peep 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's a brief summary of these directory 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's 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 what you want 💖 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's ~/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, bestie, don't overdo it 💀)
  • -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. Plus, from the text menu you 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's 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's 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 🌼

Okay bestie, so for scripting and debugging (like, when you're automating stuff or hunting down a weird bug), install-tl peeks at these environment variables. Fr fr, for a normal human doing a normal user installation? You do not need to care about these. They're giving developer-only backstage access. 💅

  • NOPERLDOC — literally just don't try to run the --help message through perldoc. That's it. That's the whole job. ✨
  • TEXLIVE_DOWNLOADER, TL_DOWNLOAD_PROGRAM, TL_DOWNLOAD_ARGS, TEXLIVE_PREFER_OWN — these override the normal choice of the download and other utility programs. Head to the tlmgr documentation for the deets, like https://tug.org/texlive/doc/tlmgr.html#ENVIRONMENT-VARIABLES. 🫶
  • TEXLIVE_INSTALL_ENV_NOCHECK — omits the check for environment variables containing the string tex. Ngl this one exists because people developing TeX-related software are likely to have a whole pile of such variables lying around, and the check would just be annoying. 😭
  • TEXLIVE_INSTALL_NO_CONTEXT_CACHE — omits creating the ConTeXt cache. Super useful for redistributors, iykyk. 🎀
  • TEXLIVE_INSTALL_NO_DISKCHECK — if set to 1, omit the free disk space check. By default, if a POSIX-compliant df program (one that supports -Pk) is available, the installer checks for available disk space in the selected installation location, and will abort installation if there's insufficient disk space, plus a margin of 100MB. An equivalent check is made on Windows (not involving df). No cap, that margin is doing the lord's work. ⭐
  • TEXLIVE_INSTALL_NO_RESUME — omits the check for installing on top of a previous installation, and then asking about importing previous settings. Skipping the whole "wait, have we met before?" moment. 🙈
  • TEXLIVE_INSTALL_NO_WELCOME — omits printing the welcome message after a successful installation, e.g., when testing. (Sad, honestly — the welcome message is a vibe. But okay.) 🌸
  • TEXLIVE_INSTALL_PAPER — sets 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 — these specify the respective directories. TEXLIVE_INSTALL_PREFIX defaults to /usr/local/texlive. You can see all the defaults by running the installer interactively and then typing D for the directory menu. ✨
Heads up bestie: the various command line options for specifying directories override these environment variables. And since specifying both is usually accidental, a warning is given if the values are different. The installer is literally looking out for you. 💖

🗂️ DIRECTORY TREES 🗂️

There are, and I cannot stress this enough, a plethora of ways to specify the plethora of directory trees used by TeX Live. But by far the simplest — and the recommended — approach is to not change anything. The defaults suffice for the vast majority of installations. Like, genuinely. Leave it alone. It's giving "don't fix what isn't broken." 💅

But for the sake of explanation, here's the rundown 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. 🦋

System directories (change them as a group with --texdir):

  • TEXMFLOCAL — default /usr/local/texlive/texmf-local; group change --texdir; single change --texmflocal
  • TEXMFSYSVAR — default /usr/local/texlive/YYYY/texmf-var; group change --texdir; single change --texmfsysvar
  • TEXMFSYSCONFIG — default /usr/local/texlive/YYYY/texmf-config; group change --texdir; single change --texmfsysconfig

User directories (change them as a group with --texuserdir):

  • TEXMFHOME — default ~/texmf; group change --texuserdir; single change --texmfhome
  • TEXMFVAR — default ~/.texliveYYYY/texmf-var; group change --texuserdir; single change --texmfvar
  • TEXMFCONFIG — default ~/.texliveYYYY/texmf-config; group change --texuserdir; single change --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. It's a whole hierarchy, bestie. 👑

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 — literally the whole point. 🫶 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. The installer is being smart about it. ✨

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. 😭 Yeah. Inscrutable. Perl. Errors. You know the vibe.

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. You got this. 🫶

By the way — do not try to use install-tl to adjust options or installed packages in an existing installed tree. Use tlmgr instead. That's not a suggestion, that's the whole rule. 💅

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. Iconic behaviour, honestly. 🌈

$Id: install-tl 74223 2025-02-23 16:38:14Z karl $

And that's a wrap, bestie! 🎀 This page ships as perl v5.42.0, dated 2025-02-23, filed under INSTALL-TL(1) — go forth and install some TeX Live. Slay. 💖✨

📦 where this page comes from
  • alpine 3.24: texmf-dist-doc 2026.0-r0 · LPPL-1.0 AND LPPL-1.1 AND LPPL-1.2 AND LPPL-1.3a AND LPPL-1.3c AND GPL-2.0-only
  • 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms