INSTALL-TL(1)

📦
version 78361 · 9 versions
, in debian trixie, fedora 44, ubuntu questing

💖 install-tl(1) 💖

Manual name: install-tl(1) · Section: User Contributed Perl Documentation

✨ NAME ✨

okay so install-tl is the TeX Live cross-platform installer 🎀 It works on every platform TeX Live supports, which is honestly iconic.

🌸 SYNOPSIS 🌸

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

📖 DESCRIPTION 📖

bestie, this installer builds a runnable TeX Live installation from all kinds of media 💅 You can install over the network, from a local hard disk, from a DVD, and more. If you're still figuring out how to download TeX Live in the first place, check out <https://tug.org/texlive/acquire.html> ✨

okay the core idea is this: you pick one of the top-level schemes. Each scheme is defined as a different set of collections and packages. A collection is a group of packages, and a package is where the actual files live 🧚 Every package belongs to exactly one collection, but schemes can mix any combo of packages and collections.

Inside the installer, you can pick a scheme and tweak which collections get installed. You cannot pick individual packages there, though 🙈 If you want to work at the package level, use tlmgr (more on that just below) once the initial install is done.

The default is scheme-full, which installs everything. And ngl, it is highly recommended 🔥

🦋 REFERENCES 🦋

post-install configuration, package updates, and so much more get handled by tlmgr(1), the TeX Live Manager 💜 <https://tug.org/texlive/tlmgr.html>

the most up-to-date version of this installer documentation lives on the internet at <https://tug.org/texlive/doc/install-tl.html> 🌈

for step-by-step instructions, check <https://tug.org/texlive/quickinstall.html> 🍓

for the full TeX Live documentation, go to <https://tug.org/texlive/doc> 📚✨

🎀 EXAMPLES 🎀

so with no options at all, install-tl drops you into an interactive menu where basically every default can be changed 💅 With options, you can seed the settings in different ways, or run the whole install without any interaction. Here are some examples, bestie:

install-tl --paper=letter Sets the paper size. The only allowed values are letter and (the default) a4 📄

install-tl --scheme scheme Sets the installation scheme. The default is full. For the full list of schemes, open the interactive S menu 👑

install-tl --no-interaction Installs right away after parsing your options, skipping the interactive menu entirely 🚀

install-tl --profile texlive.profile Installs with no interaction, using the TL profile file you give it. See "PROFILES" below for the deets 🧾 If you want to initialize from the profile and then enter the interactive menu, add --init-from-profile 💖

Full documentation follows 🫶

✨ OPTIONS ✨

okay so, every option can be given in any order, and you can use either a single leading - or a double --, no judgement 💅 An argument value can be separated from its option by a space or by =.

The options that customize the installation can also be picked in the interactive menus, whether GUI or text.

  • -gui [[=]module], -no-gui — ok this one is a bit of a mood 🎀
    • If you don't give a module, it starts the Tcl/Tk GUI installer (see below).
    • If you do give a module, it loads that installer module. Right now these are the supported ones:
      • text — the text mode interface. This is the default on Unix systems, Macs included, and it's the same as -no-gui 🖥️
      • tcl (or perltk or wizard or expert or nothing at all) — the Tcl/Tk interface, which is the default on Windows 🪟 It starts with a small set of config options, roughly what the old wizard option gave you. There's also an Advanced button that takes you to a screen with roughly the same options as the old perltk interface ✨
    • The default GUI needs Tcl/Tk. This used to come standard on Macs, but it's been removed in the latest macOS releases 💀 It's often already installed on GNU/Linux, or you can easily grab it from your distro's package manager. For Windows, TeX Live ships its own Tcl/Tk runtime 🫶
  • -lang llcode — if the Tcl GUI's built-in language detection misses, you can force a language with an ISO 639-1-based language code 🌍 Currently supported (though not every language is fully translated yet) are: English (en, the 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 — this is where you tell the installer where to get the packages from 📦 It can be a directory name, or a URL using http(s), ftp, or scp. The tlmgr docs have all the details: <https://tug.org/texlive/doc/tlmgr.html#OPTIONS> 💜
    • By default, the installer picks a mirror automatically, using <https://mirror.ctan.org/systems/texlive/tlnet>, and then sticks with that mirror for the whole download. You can use the special argument ctan as a shortcut for this. (Check <https://ctan.org> for more on CTAN and its mirrors 🧚)
    • Once the installation is done, you can use that installation as the repository for another one 🔁 If you installed less than the full scheme (the one with every package), the list of available schemes gets adjusted to match.
  • -select-repository — lets you pick a specific mirror from the current list of active CTAN mirrors 🗺️ This is supported in the text and gui installer modes. It'll also offer to install from local media if it's available, or from a repository you gave on the command line. It's super useful when the default automatic redirection picks a sus host for you 🙈
  • -all-options — normally, options that don't apply to your current platform are hidden (so on Unix, the Windows-only ones don't show up) 🙃 This option shows them anyway, so you can configure those "foreign" settings too 👀
  • -custom-bin path — the move if you've built your own set of TeX Live binaries, maybe because TL doesn't provide precompiled ones for your platform 🛠️ This points the installer at a directory holding the binaries for your current system. The install carries on as usual, but at the very end, everything from path gets copied into bin/custom/ under your installation directory. That bin/custom/ folder is what gets added to the path for the post-install actions. If you want to install multiple custom binary sets, manually rename custom before each one 💅
  • -no-installation — Skips the actual installation entirely. It's for debugging the initialization and setup routines without touching your disk, so nothing gets written. 🧪
  • -no-interaction — Skips the interactive menu and goes straight into the installation after initialization and option parsing. It also skips checking for a previous installation and asking whether to import your old settings. ⚡
  • -no-persistent-downloads, -persistent-downloads — For network installs, the persistent option tries to set up one connection using the "LWP" Perl module. That one connection gets reused for the whole session instead of opening a new download for every package, which usually gives a big speed boost. 🚀

Persistent downloads are on by default. If LWP can't be set up, the installer falls back to "wget". To turn off LWP and persistent connections, use "-no-persistent-downloads". 💅

  • -no-verify-downloads — By default, if a GnuPG gpg binary is found in PATH, downloads get checked against a cryptographic signature. This option turns that checking off. The full scoop is in the Crytographic Verification section of the "tlmgr" documentation, e.g., <https://tug.org/texlive/doc/tlmgr.html#CRYPTOGRAPHIC-VERIFICATION> 🔐
  • -non-admin — Windows only. It sets everything up for the current user instead of for all users. 🪟
  • -paper "a4"|"letter" — Sets the default paper size for all TeX Live programs to whatever you pick. The default is "a4". You can change it later after installing with the tlmgr paper command. 📄
  • -portable — Installs for portable use, like on a USB stick. Check the "instopt_portable" description further down for the details. 🧳
  • -print-platform — Prints the TeX Live identifier for your detected platform (hardware and operating system combo) to standard output, then exits. "-print-arch" is a synonym, so either one works. 🖨️
  • -profile profile_file — Loads profile_file and runs the installation with zero user interaction, which means a batch (unattended) install. Environment variables get ignored here. See "PROFILES" below. 🤖
  • -q — Hides the normal informational messages. Shh 🤫
  • -scheme scheme — Schemes are the highest level of package grouping in TeX Live. The default is the "full" scheme, which includes everything, but this option overrides that. The scheme value can optionally start with the prefix "scheme-". Which scheme names are available depends on what your package repository provides, so check the interactive menu list to see them. 📚
  • -texdir dir — Sets the system installation directory. The default is "/usr/local/texlive/YYYY" for release YYYY. Using this also makes "TEXMFLOCAL", "TEXMFSYSCONFIG", and "TEXMFSYSVAR" subdirectories of dir, so you don't have to set each one yourself. 🗂️

There's a quick summary of these directory trees under "DIRECTORY TREES" below. For the full details on the default trees and what they're meant for, check the main TeX Live documentation at <https://tug.org/texlive/doc>. 📖

  • -texuserdir dir — Sets the user installation directory. The default is "~/.texliveYYYY", except on Macs, where there's no leading dot. Using this also makes "TEXMFHOME", "TEXMFCONFIG", and "TEXMFVAR" subdirectories of dir. 👩‍💻
  • -texmflocal dir — Sets the "TEXMFLOCAL" directory. The default is "/usr/local/texlive/texmf-local", which is one level up from the main installation. That way, locally installed packages can be used across releases, which is usually what you want. Using "-texdir" changes this and puts "TEXMFLOCAL" under the main tree. The "-texmflocal" option can be used to point at an explicit directory. 🏠

Anything installed here has to follow the TeX directory structure (TDS), e.g., "TEXMFHOME/tex/latex/mypkg/mypkg.sty". TDS reference: <https://tug.org/tds>. 🧩

  • -texmfhome dir — Sets the "TEXMFHOME" directory. The default is "~/texmf", except on Macs, where it's "~/Library/texmf". Just like "TEXMFLOCAL", the "-texuserdir" option changes this default.

Also just like "TEXMFLOCAL", anything installed here must follow the TDS. 🫶

  • -texmfsysconfig dir, -texmfsysvar dir — Sets the "TEXMFSYSCONFIG" and "TEXMFSYSVAR" system directories. ⚙️
  • -texmfconfig dir, -texmfvar dir — Sets the "TEXMFCONFIG" and "TEXMFVAR" user directories. The defaults are "~/.texliveYYYY/texmf-{config,var}", except on Macs, where the leading dot is dropped ("~/texliveYYYY/..."). 🌱
  • -v — Turns on verbose debugging messages. Repeat it for maximum debugging: "-v -v". More repeats are accepted but ignored, so you're already at the max. 🔍
  • -version, --version — Prints the version information and exits. If "-v" is also given, the versions of the TeX Live modules used get reported too. 🏷️

✨ PROFILES ✨

A profile file normally has all the values needed to do an installation. After a normal installation finishes, a profile for that exact installation gets written to the file "tlpkg/texlive.profile". You can also pick "P" from the text menu anytime to save your current setup as a profile. These are small text files, so feel free to peruse and edit them however you like. 📝

You can pass a profile file as the argument to "-profile", for example to redo the exact same installation on a different system. Or you can make a custom profile, which is easiest to do by starting from a generated one and changing values. An empty profile file makes the installer use the defaults. 💖

Heads up: the installer only supports selection by scheme and collections, not individual packages. So packages can't be specified in profile files either. If you want to work at the package level, use "tlmgr". 🙃

Inside a profile file, each line looks like this:

variable [value]

Lines starting with "#" are comments. The possible variable names are listed below. Values, when present, are either 0 or 1 for booleans, or strings (which must be written 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 get installed, without listing them out explicitly. That scheme's collections might change over time, but this makes profile files way easier to maintain. ✨ If any collections are specified in a profile, though, the scheme gets ignored and all the collections you want must be listed explicitly. 🚨

For example, this line:

selected_scheme scheme-small

along with definitions for the installation directories (covered below under "path options") is enough to install the "small" scheme with all default options. The schemes are described in the "S" menu in the text installer, or the equivalent. 🌷

Besides "selected_scheme", here are the other variable names supported in a profile: 💜

🎀 collection options (prefix "collection-") 🎀

Collections are specified with a variable name that has the prefix "collection-" followed by a collection name. There's no value. For instance, "collection-basic". The collections are described in the "C" menu. 📦

Schemes, collections, and packages are all ultimately defined by the files in the "tlpkg/tlpsrc/" source directory. 🗃️

🗺️ path options 🗺️

It's best to define all of these, even if they won't be used in a given installation. That way you avoid accidentally 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) — Adjusts the "PATH" environment variable. 🧭
  • "instopt_adjustrepo" (default 1) — Sets the remote repository to a multiplexed CTAN mirror after installation. See "-repository" above. 🪞
  • "instopt_letter" (default 0) — Makes letter size paper the default instead of a4. 📃
  • "instopt_portable" (default 0) — Installs for portable use, like on a USB stick, without touching the host system. Specifically, this forces the user directories "TEXMFHOME", "TEXMFCONFIG", and "TEXMFVAR" to be identical to the system directories "TEXMFLOCAL", "TEXMFSYSCONFIG", and "TEXMFSYSVAR", respectively. This happens regardless of other options and environment variable.)

On Windows, it also disables the desktop integration, path adjustment, and file associations actions that usually get performed. 🪟

  • "instopt_write18_restricted" (default 1) — Enables "\write18" for a restricted set of programs. 🔒

🧁 tlpdb options (prefix "tlpdbopt_") 🧁

The definitive list lives in "tlpkg/TeXLive/TLConfig.pm", in the hash %TeXLive::TLConfig::TLPDBOptions, along with explanations. Every item listed 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 (the directories under "bin/"), the variable "binary_"PLATFORM can be set with the 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, lots of profile variables had different names. Those aren't documented here, so check the "install-tl" source if you need them. They're still accepted and get transformed to the names above. When a profile is written, the names above are always used. 🔄

For more details on all of the above options, check the TeX Live installation manual, linked from <https://tug.org/texlive/doc>. 🌈

✨ ENVIRONMENT VARIABLES ✨

okay so install-tl has a bunch of environment variables it peeks at for scripting and debugging 🧚 they're not really for normal installs, so don't stress if you never touch them bestie 💅

  • NOPERLDOC — tells it NOT to run the --help message through perldoc 🙈
  • TEXLIVE_DOWNLOADER, TL_DOWNLOAD_PROGRAM, TL_DOWNLOAD_ARGS, TEXLIVE_PREFER_OWN — these override the usual picks for the download and other utility programs 🔥 the full lowdown lives in the tlmgr docs, check the vibes at https://tug.org/texlive/doc/tlmgr.html#ENVIRONMENT-VARIABLES
  • TEXLIVE_INSTALL_ENV_NOCHECK — skips the check for any environment variable containing the string tex 💀 honestly this one is for the devs, because if you're building TeX-related software you're probably drowning in those variables anyway
  • TEXLIVE_INSTALL_NO_CONTEXT_CACHE — skips creating the ConTeXt cache 🌸 this one is especially useful for redistributors
  • TEXLIVE_INSTALL_NO_DISKCHECK — if set to 1, the free disk space check gets omitted 🙅‍♀️ by default, if a POSIX-compliant df (one that supports -Pk) is around, the installer checks the space in your chosen install location and will abort if it's short, with a 100MB margin on top. Windows does an equivalent check that doesn't use df at all 🫶
  • TEXLIVE_INSTALL_NO_RESUME — skips the check for installing on top of a previous install and then asking if you want to import your old settings ✨
  • TEXLIVE_INSTALL_NO_WELCOME — skips the welcome message after a successful install, which is handy when you're testing 🎀
  • TEXLIVE_INSTALL_PAPER — sets the default paper size for every relevant program. It has to be either letter or a4, and 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 set the matching directories 🗂️ TEXLIVE_INSTALL_PREFIX defaults to /usr/local/texlive. If you want to see every default, run the installer interactively and type D for the directory menu 👑

The command line options for directories beat these env vars, so if you set both, you'll get a warning when the values don't match, because that's usually an accident 😭

🗺️ DIRECTORY TREES 🗺️

okay so TeX Live has a PLETHORA of directory trees, and there are a plethora of ways to point at them 😵‍💫 the simplest, most recommended move is to change NOTHING. The defaults cover the vast majority of installs, so you're good 💖

BUT for the sake of explaining, here's the table of trees and the command line options that change them. The first group of three are system directories, the second group of three are user directories, and the two groups are pretty 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    |
  +----------------+--------------------------------------+--------------+------------------+

Also, like we said earlier, every tree has an environment variable TEXLIVE_INSTALL_tree that overrides its default ✨ command line and profile settings both beat env var settings, so the order is basically: command line and profile first, then env vars, then defaults 💅

The defaults shift a little on Macs, as explained above in "OPTIONS" 🍎

Here's the tea on ~ (the home shortcut) 🫖 for the user trees, the default value uses ~, and it stays as a literal ~ in texmf.cnf. That way every user gets their own TEXMFHOME and friends, just like it's supposed to be 🌈 for the system trees though, if you use ~ during install, it's treated as typing shorthand, and the expanded home directory gets written into texmf.cnf. It doesn't make sense to have user-specific system directories, obviously 🙄

For more on the directory trees and what they're meant for, check the main TeX Live docs at https://tug.org/texlive/doc 📚

🐛 BUGS 🐛

okay real talk, this part is a little spicy 🌶️ The install-tl script copies itself into the installed tree. Usually you can run it from there, using the installed tree as the source for another install, and it's all good 🫶 BUT every once in a while the code in the new install-tl and the infrastructure might not vibe, and you get (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 out of the installation. Feel free to report the issue too, because usually the code can be easily synced up again 🔧

Also, DO NOT try to use install-tl to adjust options or installed packages in an existing installed tree 🚫 use tlmgr instead, bestie. Seriously.

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 73024 2024-12-03 17:12:38Z karl $ 🌷

Anyway, that's the whole page, bestie 💜 install-tl from perl v5.40.0, last touched 2024-12-03, all wrapped up as INSTALL-TL(1). Go install something iconic ✨🌈👑

📦 where this page comes from