1TLMGR(1) User Contributed Perl Documentation TLMGR(1)
2
6 tlmgr - the native TeX Live Manager
7
9 tlmgr [option...] action [option...] [operand...]
10
12 tlmgr manages an existing TeX Live installation, both packages and
13 configuration options. For information on initially downloading and
14 installing TeX Live, see <https://tug.org/texlive/acquire.html>.
15 The most up-to-date version of this documentation (updated nightly from
17 the development sources) is available at
18 <https://tug.org/texlive/tlmgr.html>, along with procedures for
19 updating "tlmgr" itself and information about test versions.
20 TeX Live is organized into a few top-level schemes, each of which is
22 specified as a different set of collections and packages, where a
23 collection is a set of packages, and a package is what contains actual
24 files. Schemes typically contain a mix of collections and packages,
25 but each package is included in exactly one collection, no more and no
26 less. A TeX Live installation can be customized and managed at any
27 level.
28 See <https://tug.org/texlive/doc> for all the TeX Live documentation
30 available.
31
33 After successfully installing TeX Live, here are a few common
34 operations with "tlmgr":
35 "tlmgr option repository ctan"
37 "tlmgr option repository http://mirror.ctan.org/systems/texlive/tlnet"
38 Tell "tlmgr" to use a nearby CTAN mirror for future updates; useful
39 if you installed TeX Live from the DVD image and want to have
40 continuing updates. The two commands are equivalent; "ctan" is
41 just an alias for the given url. Caveat: "mirror.ctan.org"
42 resolves to many different hosts, and they are not perfectly
43 synchronized; we recommend updating only daily (at most), and not
44 more often.
45 "tlmgr update --list"
47 Report what would be updated without actually updating anything.
48 "tlmgr update --all"
50 Make your local TeX installation correspond to what is in the
51 package repository (typically useful when updating from CTAN).
52 "tlmgr info" what
54 Display detailed information about a package what, such as the
55 installation status and description, of searches for what in all
56 packages.
57 For all the capabilities and details of "tlmgr", please read the
59 following voluminous information.
60
62 The following options to "tlmgr" are global options, not specific to
63 any action. All options, whether global or action-specific, can be
64 given anywhere on the command line, and in any order. The first non-
65 option argument will be the main action. In all cases, "--"option and
66 "-"option are equivalent, and an "=" is optional between an option name
67 and its value.
68 --repository url|path
70 Specify the package repository from which packages should be
71 installed or updated, either a local directory or network location,
72 as below. This overridesthe default package repository found in the
73 installation's TeX Live Package Database (a.k.a. the TLPDB, which
74 is given entirely in the file "tlpkg/texlive.tlpdb").
75 This "--repository" option changes the location only for the
77 current run; to make a permanent change, use "option repository"
78 (see the "option" action).
79 As an example, you can choose a particular CTAN mirror with
81 something like this:
82 -repository http://ctan.example.org/its/ctan/dir/systems/texlive/tlnet
84 Of course a real hostname and its particular top-level CTAN
86 directory have to be specified. The list of CTAN mirrors is
87 available at <https://ctan.org/mirrors>.
88 Here's an example of using a local directory:
90 -repository /local/TL/repository
92 For backward compatibility and convenience, "--location" and
94 "--repo" are accepted as aliases for this option.
95 Locations can be specified as any of the following:
97 "/some/local/dir"
99 "file:/some/local/dir"
100 Equivalent ways of specifying a local directory.
101 "ctan"
103 "http://mirror.ctan.org/systems/texlive/tlnet"
104 Pick a CTAN mirror automatically, trying for one that is both
105 nearby and up-to-date. The chosen mirror is used for the entire
106 download. The bare "ctan" is merely an alias for the full url.
107 (See <https://ctan.org> for more about CTAN and its mirrors.)
108 "http://server/path/to/tlnet"
110 Standard HTTP. If the (default) LWP method is used, persistent
111 connections are supported. TL can also use "curl" or "wget" to
112 do the downloads, or an arbitrary user-specified program, as
113 described in the "tlmgr" documentation
114 (<https://tug.org/texlive/doc/tlmgr.html#ENVIRONMENT-VARIABLES>).
115 "https://server/path/to/tlnet"
117 Again, if the (default) LWP method is used, this supports
118 persistent connections. Unfortunately, some versions of "wget"
119 and "curl" do not support https, and even when "wget" supports
120 https, certificates may be rejected even when the certificate
121 is fine, due to a lack of local certificate roots. The simplest
122 workaround for this problem is to use http or ftp.
123 "ftp://server/path/to/tlnet"
125 If the (default) LWP method is used, persistent connections are
126 supported.
127 "user@machine:/path/to/tlnet"
129 "scp://user@machine/path/to/tlnet"
130 "ssh://user@machine/path/to/tlnet"
131 These forms are equivalent; they all use "scp" to transfer
132 files. Using "ssh-agent" is recommended. (Info:
133 <https://en.wikipedia.org/wiki/OpenSSH>,
134 <https://en.wikipedia.org/wiki/Ssh-agent>.)
135 If the repository is on the network, trailing "/" characters and/or
137 trailing "/tlpkg" and/or "/archive" components are ignored.
138 --gui [action]
140 "tlmgr" has a graphical interface as well as the command line
141 interface. You can give this option, "--gui", together with an
142 action to be brought directly into the respective screen of the
143 GUI. For example, running
144 tlmgr --gui update
146 starts you directly at the update screen. If no action is given,
148 the GUI will be started at the main screen.
149 Note that the new GUIs, tlshell and tlcockpit, are started up as
151 separate programs.
152 --gui-lang llcode
154 By default, the GUI tries to deduce your language from the
155 environment (on Windows via the registry, on Unix via
156 "LC_MESSAGES"). If that fails you can select a different language
157 by giving this option with a language code (based on ISO 639-1).
158 Currently supported (but not necessarily completely translated)
159 are: English (en, default), Czech (cs), German (de), French (fr),
160 Italian (it), Japanese (ja), Dutch (nl), Polish (pl), Brazilian
161 Portuguese (pt_BR), Russian (ru), Slovak (sk), Slovenian (sl),
162 Serbian (sr), Ukrainian (uk), Vietnamese (vi), simplified Chinese
163 (zh_CN), and traditional Chinese (zh_TW).
164 Tlshell shares its message catalog with tlmgr.
166 --debug-translation
168 In GUI mode, this switch tells "tlmgr" to report any untranslated
169 (or missing) messages to standard error. This can help translators
170 to see what remains to be done.
171 --machine-readable
173 Instead of the normal output intended for human consumption, write
174 (to standard output) a fixed format more suitable for machine
175 parsing. See the "MACHINE-READABLE OUTPUT" section below.
176 --no-execute-actions
178 Suppress the execution of the execute actions as defined in the
179 tlpsrc files. Documented only for completeness, as this is only
180 useful in debugging.
181 --package-logfile file
183 "tlmgr" logs all package actions (install, remove, update, failed
184 updates, failed restores) to a separate log file, by default
185 "TEXMFSYSVAR/web2c/tlmgr.log". This option allows you to specify a
186 different file for the log.
187 --pause
189 This option makes "tlmgr" wait for user input before exiting.
190 Useful on Windows to avoid disappearing command windows.
191 --persistent-downloads
193 --no-persistent-downloads
194 For network-based installations, this option (on by default) makes
195 "tlmgr" try to set up a persistent connection (using the "LWP" Perl
196 module). The idea is to open and reuse only one connection per
197 session between your computer and the server, instead of initiating
198 a new download for each package.
199 If this is not possible, "tlmgr" will fall back to using "wget".
201 To disable these persistent connections, use
202 "--no-persistent-downloads".
203 --pin-file
205 Change the pinning file location from
206 "TEXMFLOCAL/tlpkg/pinning.txt" (see "Pinning" below). Documented
207 only for completeness, as this is only useful in debugging.
208 --usermode
210 Activates user mode for this run of "tlmgr"; see "USER MODE" below.
211 --usertree dir
213 Uses dir for the tree in user mode; see "USER MODE" below.
214 --verify-repo=[none|main|all]
216 Defines the level of verification done: If "none" is specified, no
217 verification whatsoever is done. If "main" is given and a working
218 GnuPG ("gpg") binary is available, all repositories are checked,
219 but only the main repository is required to be signed. If "all" is
220 given, then all repositories need to be signed. See "CRYPTOGRAPHIC
221 VERIFICATION" below for details.
222 The standard options for TeX Live programs are also accepted:
224 "--help/-h/-?", "--version", "-q" (no informational messages), "-v"
225 (debugging messages, can be repeated). For the details about these,
226 see the "TeXLive::TLUtils" documentation.
227 The "--version" option shows version information about the TeX Live
229 release and about the "tlmgr" script itself. If "-v" is also given,
230 revision number for the loaded TeX Live Perl modules are shown, too.
231
233 help
234 Display this help information and exit (same as "--help", and on the
235 web at <https://tug.org/texlive/doc/tlmgr.html>). Sometimes the
236 "perldoc" and/or "PAGER" programs on the system have problems,
237 resulting in control characters being literally output. This can't
238 always be detected, but you can set the "NOPERLDOC" environment
239 variable and "perldoc" will not be used.
240 version
242 Gives version information (same as "--version").
243 If "-v" has been given the revisions of the used modules are reported,
245 too.
246 backup
248 backup [option...] --all
249 backup [option...] pkg...
250 If the "--clean" option is not specified, this action makes a
251 backup of the given packages, or all packages given "--all". These
252 backups are saved to the value of the "--backupdir" option, if that
253 is an existing and writable directory. If "--backupdir" is not
254 given, the "backupdir" option setting in the TLPDB is used, if
255 present. If both are missing, no backups are made.
256 If the "--clean" option is specified, backups are pruned (removed)
258 instead of saved. The optional integer value N may be specified to
259 set the number of backups that will be retained when cleaning. If
260 "N" is not given, the value of the "autobackup" option is used. If
261 both are missing, an error is issued. For more details of backup
262 pruning, see the "option" action.
263 Options:
265 --backupdir directory
267 Overrides the "backupdir" option setting in the TLPDB. The
268 directory argument is required and must specify an existing,
269 writable directory where backups are to be placed.
270 --all
272 If "--clean" is not specified, make a backup of all packages in
273 the TeX Live installation; this will take quite a lot of space
274 and time. If "--clean" is specified, all packages are pruned.
275 --clean[=N]
277 Instead of making backups, prune the backup directory of old
278 backups, as explained above. The optional integer argument N
279 overrides the "autobackup" option set in the TLPDB. You must
280 use "--all" or a list of packages together with this option, as
281 desired.
282 --dry-run
284 Nothing is actually backed up or removed; instead, the actions
285 to be performed are written to the terminal.
286 candidates pkg
288 Shows the available candidate repositories for package pkg. See
289 "MULTIPLE REPOSITORIES" below.
290 check [option...] [files|depends|executes|runfiles|all]
292 Executes one (or all) check(s) on the consistency of the installation.
293 files
295 Checks that all files listed in the local TLPDB ("texlive.tlpdb")
296 are actually present, and lists those missing.
297 depends
299 Lists those packages which occur as dependencies in an installed
300 collection, but are themselves not installed, and those packages
301 which are not contained in any collection.
302 If you call "tlmgr check collections" this test will be carried out
304 instead since former versions for "tlmgr" called it that way.
305 executes
307 Check that the files referred to by "execute" directives in the TeX
308 Live Database are present.
309 runfiles
311 List those filenames that are occurring more than one time in the
312 runfiles sections.
313 Options:
315 --use-svn
317 Use the output of "svn status" instead of listing the files; for
318 checking the TL development repository.
319 conf
321 conf [texmf|tlmgr|updmap [--conffile file] [--delete] [key [value]]]
322 conf auxtrees [--conffile file] [show|add|remove] [value]
323 With only "conf", show general configuration information for TeX
324 Live, including active configuration files, path settings, and
325 more. This is like running "texconfig conf", but works on all
326 supported platforms.
327 With one of "conf texmf", "conf tlmgr", or "conf updmap", shows all
329 key/value pairs (i.e., all settings) as saved in "ROOT/texmf.cnf",
330 the user-specific "tlmgr" configuration file (see below), or the
331 first found (via "kpsewhich") "updmap.cfg" file, respectively.
332 If key is given in addition, shows the value of only that key in
334 the respective file. If option --delete is also given, the value
335 in the given configuration file is entirely removed (not just
336 commented out).
337 If value is given in addition, key is set to value in the
339 respective file. No error checking is done!
340 The "PATH" value shown by "conf" is as used by "tlmgr". The
342 directory in which the "tlmgr" executable is found is automatically
343 prepended to the PATH value inherited from the environment.
344 Here is a practical example of changing configuration values. If
346 the execution of (some or all) system commands via "\write18" was
347 left enabled during installation, you can disable it afterwards:
348 tlmgr conf texmf shell_escape 0
350 The subcommand "auxtrees" allows adding and removing arbitrary
352 additional texmf trees, completely under user control. "auxtrees
353 show" shows the list of additional trees, "auxtrees add" tree adds
354 a tree to the list, and "auxtrees remove" tree removes a tree from
355 the list (if present). The trees should not contain an "ls-R" file
356 (or files will not be found if the "ls-R" becomes stale). This
357 works by manipulating the Kpathsea variable "TEXMFAUXTREES", in (by
358 default) "ROOT/texmf.cnf". Example:
359 tlmgr conf auxtrees add /quick/test/tree
361 tlmgr conf auxtrees remove /quick/test/tree
362 In all cases the configuration file can be explicitly specified via
364 the option "--conffile" file, e.g., if you don't want to change the
365 system-wide configuration.
366 Warning: The general facility for changing configuration values is
368 here, but tinkering with settings in this way is strongly
369 discouraged. Again, no error checking on either keys or values is
370 done, so any sort of breakage is possible.
371 dump-tlpdb [option...] [--json]
373 Dump complete local or remote TLPDB to standard output, as-is. The
374 output is analogous to the "--machine-readable" output; see "MACHINE-
375 READABLE OUTPUT" section.
376 Options:
378 --local
380 Dump the local TLPDB.
381 --remote
383 Dump the remote TLPDB.
384 --json
386 Instead of dumping the actual content, the database is dumped as
387 JSON. For the format of JSON output see
388 "tlpkg/doc/JSON-formats.txt", format definition "TLPDB".
389 Exactly one of "--local" and "--remote" must be given.
391 In either case, the first line of the output specifies the repository
393 location, in this format:
394 "location-url" "\t" location
396 where "location-url" is the literal field name, followed by a tab, and
398 location is the file or url to the repository.
399 Line endings may be either LF or CRLF depending on the current
401 platform.
402 generate
404 generate [option...] language
405 generate [option...] language.dat
406 generate [option...] language.def
407 generate [option...] language.dat.lua
408 The "generate" action overwrites any manual changes made in the
410 respective files: it recreates them from scratch based on the
411 information of the installed packages, plus local adaptions. The TeX
412 Live installer and "tlmgr" routinely call "generate" for all of these
413 files.
414 For managing your own fonts, please read the "updmap --help"
416 information and/or <https://tug.org/fonts/fontinstall.html>.
417 For managing your own formats, please read the "fmtutil --help"
419 information.
420 In more detail: "generate" remakes any of the configuration files
422 "language.dat", "language.def", and "language.dat.lua" from the
423 information present in the local TLPDB, plus locally-maintained files.
424 The locally-maintained files are "language-local.dat",
426 "language-local.def", or "language-local.dat.lua", searched for in
427 "TEXMFLOCAL" in the respective directories. If local additions are
428 present, the final file is made by starting with the main file,
429 omitting any entries that the local file specifies to be disabled, and
430 finally appending the local file.
431 (Historical note: The formerly supported "updmap-local.cfg" and
433 "fmtutil-local.cnf" are no longer read, since "updmap" and "fmtutil"
434 now reads and supports multiple configuration files. Thus, local
435 additions can and should be put into an "updmap.cfg" of "fmtutil.cnf"
436 file in "TEXMFLOCAL". The "generate updmap" and "generate fmtutil"
437 actions no longer exist.)
438 Local files specify entries to be disabled with a comment line, namely
440 one of these:
441 %!NAME
443 --!NAME
444 where "language.dat" and "language.def" use "%", and "language.dat.lua"
446 use "--". In all cases, the name is the respective format name or
447 hyphenation pattern identifier. Examples:
448 %!german
450 --!usenglishmax
451 (Of course, you're not likely to actually want to disable those
453 particular items. They're just examples.)
454 After such a disabling line, the local file can include another entry
456 for the same item, if a different definition is desired. In general,
457 except for the special disabling lines, the local files follow the same
458 syntax as the master files.
459 The form "generate language" recreates all three files "language.dat",
461 "language.def", and "language.dat.lua", while the forms with an
462 extension recreates only that given language file.
463 Options:
465 --dest output_file
467 specifies the output file (defaults to the respective location in
468 "TEXMFSYSVAR"). If "--dest" is given to "generate language", it
469 serves as a basename onto which ".dat" will be appended for the
470 name of the "language.dat" output file, ".def" will be appended to
471 the value for the name of the "language.def" output file, and
472 ".dat.lua" to the name of the "language.dat.lua" file. (This is
473 just to avoid overwriting; if you want a specific name for each
474 output file, we recommend invoking "tlmgr" twice.)
475 --localcfg local_conf_file
477 specifies the (optional) local additions (defaults to the
478 respective location in "TEXMFLOCAL").
479 --rebuild-sys
481 tells "tlmgr" to run necessary programs after config files have
482 been regenerated. These are: "fmtutil-sys --all" after "generate
483 fmtutil", "fmtutil-sys --byhyphen .../language.dat" after "generate
484 language.dat", and "fmtutil-sys --byhyphen .../language.def" after
485 "generate language.def".
486 These subsequent calls cause the newly-generated files to actually
488 take effect. This is not done by default since those calls are
489 lengthy processes and one might want to made several related
490 changes in succession before invoking these programs.
491 The respective locations are as follows:
493 tex/generic/config/language.dat (and language-local.dat)
495 tex/generic/config/language.def (and language-local.def)
496 tex/generic/config/language.dat.lua (and language-local.dat.lua)
497 gui
499 Start the graphical user interface. See GUI below.
500 info
502 info [option...] pkg...
503 info [option...] collections
504 info [option...] schemes
505 With no argument, lists all packages available at the package
506 repository, prefixing those already installed with "i".
507 With the single word "collections" or "schemes" as the argument,
509 lists the request type instead of all packages.
510 With any other arguments, display information about pkg: the name,
512 category, short and long description, sizes, installation status,
513 and TeX Live revision number. If pkg is not locally installed,
514 searches in the remote installation source.
515 For normal packages (not collections or schemes), the sizes of the
517 four groups of files (run/src/doc/bin files) are shown separately.
518 For collections, the cumulative size is shown, including all
519 directly-dependent packages (but not dependent collections). For
520 schemes, the cumulative size is also shown, including all directly-
521 dependent collections and packages.
522 If pkg is not found locally or remotely, the search action is used
524 and lists matching packages and files.
525 It also displays information taken from the TeX Catalogue, namely
527 the package version, date, and license. Consider these, especially
528 the package version, as approximations only, due to timing skew of
529 the updates of the different pieces. By contrast, the "revision"
530 value comes directly from TL and is reliable.
531 The former actions "show" and "list" are merged into this action,
533 but are still supported for backward compatibility.
534 Options:
536 --list
538 If the option "--list" is given with a package, the list of
539 contained files is also shown, including those for platform-
540 specific dependencies. When given with schemes and
541 collections, "--list" outputs their dependencies in a similar
542 way.
543 --only-installed
545 If this option is given, the installation source will not be
546 used; only locally installed packages, collections, or schemes
547 are listed.
548 --only-remote
550 Only list packages from the remote repository. Useful when
551 checking what is available in a remote repository using "tlmgr
552 --repo ... --only-remote info". Note that "--only-installed"
553 and "--only-remote" cannot both be specified.
554 --data "item1,item2,..."
556 If the option "--data" is given, its argument must be a comma
557 separated list of field names from: "name", "category",
558 "localrev", "remoterev", "shortdesc", "longdesc", "installed",
559 "size", "relocatable", "depends", "cat-version", "cat-date", or
560 "cat-license". In this case the requested packages' information
561 is listed in CSV format one package per line, and the column
562 information is given by the "itemN". The "depends" column
563 contains the name of all dependencies separated by ":".
564 --json
566 In case "--json" is specified, the output is a JSON encoded
567 array where each array element is the JSON representation of a
568 single "TLPOBJ" but with additional information. For details
569 see "tlpkg/doc/JSON-formats.txt", format definition:
570 "TLPOBJINFO". If both "--json" and "--data" are given,
571 "--json" takes precedence.
572 init-usertree
574 Sets up a texmf tree for so-called user mode management, either the
575 default user tree ("TEXMFHOME"), or one specified on the command line
576 with "--usertree". See "USER MODE" below.
577 install [option...] pkg...
579 Install each pkg given on the command line, if it is not already
580 installed. (It does not touch existing packages; see the "update"
581 action for how to get the latest version of a package.)
582 By default this also installs all packages on which the given pkgs are
584 dependent. Options:
585 --dry-run
587 Nothing is actually installed; instead, the actions to be performed
588 are written to the terminal.
589 --file
591 Instead of fetching a package from the installation repository, use
592 the package files given on the command line. These files must be
593 standard TeX Live package files (with contained tlpobj file).
594 --force
596 If updates to "tlmgr" itself (or other parts of the basic
597 infrastructure) are present, "tlmgr" will bail out and not perform
598 the installation unless this option is given. Not recommended.
599 --no-depends
601 Do not install dependencies. (By default, installing a package
602 ensures that all dependencies of this package are fulfilled.)
603 --no-depends-at-all
605 Normally, when you install a package which ships binary files the
606 respective binary package will also be installed. That is, for a
607 package "foo", the package "foo.i386-linux" will also be installed
608 on an "i386-linux" system. This option suppresses this behavior,
609 and also implies "--no-depends". Don't use it unless you are sure
610 of what you are doing.
611 --reinstall
613 Reinstall a package (including dependencies for collections) even
614 if it already seems to be installed (i.e, is present in the TLPDB).
615 This is useful to recover from accidental removal of files in the
616 hierarchy.
617 When re-installing, only dependencies on normal packages are
619 followed (i.e., not those of category Scheme or Collection).
620 --with-doc
622 --with-src
623 While not recommended, the "install-tl" program provides an option
624 to omit installation of all documentation and/or source files. (By
625 default, everything is installed.) After such an installation, you
626 may find that you want the documentation or source files for a
627 given package after all. You can get them by using these options
628 in conjunction with "--reinstall", as in (using the "fontspec"
629 package as the example):
630 tlmgr install --reinstall --with-doc --with-src fontspec
632 key
634 key list
635 key add file
636 key remove keyid
637 The action "key" allows listing, adding and removing additional GPG
638 keys to the set of trusted keys, that is, those that are used to
639 verify the TeX Live databases.
640 With the "list" argument, "key" lists all keys.
642 The "add" argument requires another argument, either a filename or
644 "-" for stdin, from which the key is added. The key is added to the
645 local keyring "GNUPGHOME/repository-keys.gpg", which is normally
646 "tlpkg/gpg/repository-keys.gpg".
647 The "remove" argument requires a key id and removes the requested
649 id from the local keyring.
650 list
652 Synonym for "info".
653 option
655 option [--json] [show]
656 option [--json] showall
657 option key [value]
658 The first form, "show", shows the global TeX Live settings currently
660 saved in the TLPDB with a short description and the "key" used for
661 changing it in parentheses.
662 The second form, "showall", is similar, but also shows options which
664 can be defined but are not currently set to any value.
665 Both "show..." forms take an option "--json", which dumps the option
667 information in JSON format. In this case, both forms dump the same
668 data. For the format of the JSON output see
669 "tlpkg/doc/JSON-formats.txt", format definition "TLOPTION".
670 In the third form, with key, if value is not given, the setting for key
672 is displayed. If value is present, key is set to value.
673 Possible values for key are (run "tlmgr option showall" for the
675 definitive list):
676 repository (default package repository),
678 formats (create formats at installation time),
679 postcode (run postinst code blobs)
680 docfiles (install documentation files),
681 srcfiles (install source files),
682 backupdir (default directory for backups),
683 autobackup (number of backups to keep).
684 sys_bin (directory to which executables are linked by the path action)
685 sys_man (directory to which man pages are linked by the path action)
686 sys_info (directory to which Info files are linked by the path action)
687 desktop_integration (Windows-only: create Start menu shortcuts)
688 fileassocs (Windows-only: change file associations)
689 multiuser (Windows-only: install for all users)
690 One common use of "option" is to permanently change the installation to
692 get further updates from the Internet, after originally installing from
693 DVD. To do this, you can run
694 tlmgr option repository http://mirror.ctan.org/systems/texlive/tlnet
696 The "install-tl" documentation has more information about the possible
698 values for "repository". (For backward compatibility, "location" can
699 be used as a synonym for "repository".)
700 If "formats" is set (this is the default), then formats are regenerated
702 when either the engine or the format files have changed. Disable this
703 only when you know how and want to regenerate formats yourself.
704 The "postcode" option controls execution of per-package
706 postinstallation action code. It is set by default, and again
707 disabling is not likely to be of interest except to developers doing
708 debugging.
709 The "docfiles" and "srcfiles" options control the installation of their
711 respective file groups (documentation, sources; grouping is
712 approximate) per package. By default both are enabled (1). Either or
713 both can be disabled (set to 0) if disk space is limited or for minimal
714 testing installations, etc. When disabled, the respective files are
715 not downloaded at all.
716 The options "autobackup" and "backupdir" determine the defaults for the
718 actions "update", "backup" and "restore". These three actions need a
719 directory in which to read or write the backups. If "--backupdir" is
720 not specified on the command line, the "backupdir" option value is used
721 (if set).
722 The "autobackup" option (de)activates automatic generation of backups.
724 Its value is an integer. If the "autobackup" value is "-1", no backups
725 are removed. If "autobackup" is 0 or more, it specifies the number of
726 backups to keep. Thus, backups are disabled if the value is 0. In the
727 "--clean" mode of the "backup" action this option also specifies the
728 number to be kept. The default value is 1, so that backups are made,
729 but only one backup is kept.
730 To setup "autobackup" to "-1" on the command line, use:
732 tlmgr option -- autobackup -1
734 The "--" avoids having the "-1" treated as an option. (The "--" stops
736 parsing for options at the point where it appears; this is a general
737 feature across most Unix programs.)
738 The "sys_bin", "sys_man", and "sys_info" options are used on Unix
740 systems to control the generation of links for executables, Info files
741 and man pages. See the "path" action for details.
742 The last three options affect behavior on Windows installations. If
744 "desktop_integration" is set, then some packages will install items in
745 a sub-folder of the Start menu for "tlmgr gui", documentation, etc. If
746 "fileassocs" is set, Windows file associations are made (see also the
747 "postaction" action). Finally, if "multiuser" is set, then adaptions
748 to the registry and the menus are done for all users on the system
749 instead of only the current user. All three options are on by default.
750 paper
752 paper [a4|letter]
753 [xdvi|pdftex|dvips|dvipdfmx|context|psutils] paper [papersize|--list]
754 paper --json
755 With no arguments ("tlmgr paper"), shows the default paper size setting
757 for all known programs.
758 With one argument (e.g., "tlmgr paper a4"), sets the default for all
760 known programs to that paper size.
761 With a program given as the first argument and no paper size specified
763 (e.g., "tlmgr dvips paper"), shows the default paper size for that
764 program.
765 With a program given as the first argument and a paper size as the last
767 argument (e.g., "tlmgr dvips paper a4"), set the default for that
768 program to that paper size.
769 With a program given as the first argument and "--list" given as the
771 last argument (e.g., "tlmgr dvips paper --list"), shows all valid paper
772 sizes for that program. The first size shown is the default.
773 If "--json" is specified without other options, the paper setup is
775 dumped in JSON format. For the format of JSON output see
776 "tlpkg/doc/JSON-formats.txt", format definition "TLPAPER".
777 Incidentally, this syntax of having a specific program name before the
779 "paper" keyword is unusual. It is inherited from the longstanding
780 "texconfig" script, which supports other configuration settings for
781 some programs, notably "dvips". "tlmgr" does not support those extra
782 settings.
783 path
785 path [--w32mode=user|admin] add
786 path [--w32mode=user|admin] remove
787 On Unix, merely adds or removes symlinks for binaries, man pages,
788 and info pages in the system directories specified by the
789 respective options (see the "option" description above). Does not
790 change any initialization files, either system or personal.
791 On Windows, the registry part where the binary directory is added
793 or removed is determined in the following way:
794 If the user has admin rights, and the option "--w32mode" is not
796 given, the setting w32_multi_user determines the location (i.e., if
797 it is on then the system path, otherwise the user path is changed).
798 If the user has admin rights, and the option "--w32mode" is given,
800 this option determines the path to be adjusted.
801 If the user does not have admin rights, and the option "--w32mode"
803 is not given, and the setting w32_multi_user is off, the user path
804 is changed, while if the setting w32_multi_user is on, a warning is
805 issued that the caller does not have enough privileges.
806 If the user does not have admin rights, and the option "--w32mode"
808 is given, it must be "user" and the user path will be adjusted. If
809 a user without admin rights uses the option "--w32mode admin" a
810 warning is issued that the caller does not have enough privileges.
811 pinning
813 The "pinning" action manages the pinning file, see "Pinning" below.
814 "pinning show"
816 Shows the current pinning data.
817 "pinning add" repo pkgglob...
819 Pins the packages matching the pkgglob(s) to the repository repo.
820 "pinning remove" repo pkgglob...
822 Any packages recorded in the pinning file matching the <pkgglob>s
823 for the given repository repo are removed.
824 "pinning remove repo --all"
826 Remove all pinning data for repository repo.
827 platform
829 platform list|add|remove platform...
830 platform set platform
831 platform set auto
832 "platform list" lists the TeX Live names of all the platforms
833 (a.k.a. architectures), ("i386-linux", ...) available at the
834 package repository.
835 "platform add" platform... adds the executables for each given
837 platform platform to the installation from the repository.
838 "platform remove" platform... removes the executables for each
840 given platform platform from the installation, but keeps the
841 currently running platform in any case.
842 "platform set" platform switches TeX Live to always use the given
844 platform instead of auto detection.
845 "platform set auto" switches TeX Live to auto detection mode for
847 platform.
848 Platform detection is needed to select the proper "xz" and "wget"
850 binaries that are shipped with TeX Live.
851 "arch" is a synonym for "platform".
853 Options:
855 --dry-run
857 Nothing is actually installed; instead, the actions to be
858 performed are written to the terminal.
859 postaction
861 postaction [option...] install [shortcut|fileassoc|script] [pkg...]
862 postaction [option...] remove [shortcut|fileassoc|script] [pkg...]
863 Carry out the postaction "shortcut", "fileassoc", or "script" given
864 as the second required argument in install or remove mode (which is
865 the first required argument), for either the packages given on the
866 command line, or for all if "--all" is given.
867 Options:
869 --w32mode=[user|admin]
871 If the option "--w32mode" is given the value "user", all
872 actions will only be carried out in the user-accessible parts
873 of the registry/filesystem, while the value "admin" selects the
874 system-wide parts of the registry for the file associations.
875 If you do not have enough permissions, using "--w32mode=admin"
876 will not succeed.
877 --fileassocmode=[1|2]
879 "--fileassocmode" specifies the action for file associations.
880 If it is set to 1 (the default), only new associations are
881 added; if it is set to 2, all associations are set to the TeX
882 Live programs. (See also "option fileassocs".)
883 --all
885 Carry out the postactions for all packages
886 print-platform
888 Print the TeX Live identifier for the detected platform
889 (hardware/operating system) combination to standard output, and exit.
890 "--print-arch" is a synonym.
891 print-platform-info
893 Print the TeX Live platform identifier, TL platform long name, and
894 original output from guess.
895 remove [option...] pkg...
897 Remove each pkg specified. Removing a collection removes all package
898 dependencies (unless "--no-depends" is specified), but not any
899 collection dependencies of that collection. However, when removing a
900 package, dependencies are never removed. Options:
901 --all
903 Uninstalls all of TeX Live, asking for confirmation unless
904 "--force" is also specified.
905 --backup
907 --backupdir directory
908 These options behave just as with the update action (q.v.), except
909 they apply to making backups of packages before they are removed.
910 The default is to make such a backup, that is, to save a copy of
911 packages before removal.
912 The "restore" action explains how to restore from a backup.
914 --no-depends
916 Do not remove dependent packages.
917 --no-depends-at-all
919 See above under install (and beware).
920 --force
922 By default, removal of a package or collection that is a dependency
923 of another collection or scheme is not allowed. With this option,
924 the package will be removed unconditionally. Use with care.
925 A package that has been removed using the "--force" option because
927 it is still listed in an installed collection or scheme will not be
928 updated, and will be mentioned as "forcibly removed" in the output
929 of "tlmgr update --list".
930 --dry-run
932 Nothing is actually removed; instead, the actions to be performed
933 are written to the terminal.
934 repository
936 repository list
937 repository list path|tag
938 repository add path [tag]
939 repository remove path|tag
940 repository set path[#tag] [path[#tag] ...]
941 This action manages the list of repositories. See MULTIPLE
942 REPOSITORIES below for detailed explanations.
943 The first form ("list") lists all configured repositories and the
945 respective tags if set. If a path, url, or tag is given after the
946 "list" keyword, it is interpreted as source from where to
947 initialize a TeX Live Database and lists the contained packages.
948 This can also be an up-to-now not used repository, both locally and
949 remote. If one pass in addition "--with-platforms", for each
950 package the available platforms (if any) are listed, too.
951 The third form ("add") adds a repository (optionally attaching a
953 tag) to the list of repositories. The forth form ("remove")
954 removes a repository, either by full path/url, or by tag. The last
955 form ("set") sets the list of repositories to the items given on
956 the command line, not keeping previous settings
957 In all cases, one of the repositories must be tagged as "main";
959 otherwise, all operations will fail!
960 restore
962 restore [option...] pkg [rev]
963 restore [option...] --all
964 Restore a package from a previously-made backup.
965 If "--all" is given, try to restore the latest revision of all
967 package backups found in the backup directory.
968 Otherwise, if neither pkg nor rev are given, list the available
970 backup revisions for all packages. With pkg given but no rev, list
971 all available backup revisions of pkg.
972 When listing available packages, "tlmgr" shows the revision, and in
974 parenthesis the creation time if available (in format yyyy-mm-dd
975 hh:mm).
976 If (and only if) both pkg and a valid revision number rev are
978 specified, try to restore the package from the specified backup.
979 Options:
981 --all
983 Try to restore the latest revision of all package backups found
984 in the backup directory. Additional non-option arguments (like
985 pkg) are not allowed.
986 --backupdir directory
988 Specify the directory where the backups are to be found. If not
989 given it will be taken from the configuration setting in the
990 TLPDB.
991 --dry-run
993 Nothing is actually restored; instead, the actions to be
994 performed are written to the terminal.
995 --force
997 Don't ask questions.
998 --json
1000 When listing backups, the option "--json" turn on JSON output.
1001 The format is an array of JSON objects ("name", "rev", "date").
1002 For details see "tlpkg/doc/JSON-formats.txt", format
1003 definition: "TLBACKUPS". If both "--json" and "--data" are
1004 given, "--json" takes precedence.
1005 search
1007 search [option...] what
1008 search [option...] --file what
1009 search [option...] --all what
1010 By default, search the names, short descriptions, and long
1011 descriptions of all locally installed packages for the argument
1012 what, interpreted as a (Perl) regular expression.
1013 Options:
1015 --file
1017 List all filenames containing what.
1018 --all
1020 Search everything: package names, descriptions and filenames.
1021 --global
1023 Search the TeX Live Database of the installation medium,
1024 instead of the local installation.
1025 --word
1027 Restrict the search of package names and descriptions (but not
1028 filenames) to match only full words. For example, searching
1029 for "table" with this option will not output packages
1030 containing the word "tables" (unless they also contain the word
1031 "table" on its own).
1032 shell
1034 Starts an interactive mode, where tlmgr prompts for commands. This can
1035 be used directly, or for scripting. The first line of output is
1036 "protocol" n, where n is an unsigned number identifying the protocol
1037 version (currently 1).
1038 In general, tlmgr actions that can be given on the command line
1040 translate to commands in this shell mode. For example, you can say
1041 "update --list" to see what would be updated. The TLPDB is loaded the
1042 first time it is needed (not at the beginning), and used for the rest
1043 of the session.
1044 Besides these actions, a few commands are specific to shell mode:
1046 protocol
1048 Print "protocol n", the current protocol version.
1049 help
1051 Print pointers to this documentation.
1052 version
1054 Print tlmgr version information.
1055 quit, end, bye, byebye, EOF
1057 Exit.
1058 restart
1060 Restart "tlmgr shell" with the original command line; most useful
1061 when developing "tlmgr".
1062 load [local|remote]
1064 Explicitly load the local or remote, respectively, TLPDB.
1065 save
1067 Save the local TLPDB, presumably after other operations have
1068 changed it.
1069 get [var] =item set [var [val]]
1071 Get the value of var, or set it to val. Possible var names:
1072 "debug-translation", "machine-readable", "no-execute-actions",
1073 "require-verification", "verify-downloads", "repository", and
1074 "prompt". All except "repository" and "prompt" are booleans, taking
1075 values 0 and 1, and behave like the corresponding command line
1076 option. The "repository" variable takes a string, and sets the
1077 remote repository location. The "prompt" variable takes a string,
1078 and sets the current default prompt.
1079 If var or then val is not specified, it is prompted for.
1081 show
1083 Synonym for "info".
1084 uninstall
1086 Synonym for remove.
1087 update [option...] [pkg...]
1089 Updates the packages given as arguments to the latest version available
1090 at the installation source. Either "--all" or at least one pkg name
1091 must be specified. Options:
1092 --all
1094 Update all installed packages except for "tlmgr" itself. Thus, if
1095 updates to "tlmgr" itself are present, this will simply give an
1096 error, unless also the option "--force" or "--self" is given. (See
1097 below.)
1098 In addition to updating the installed packages, during the update
1100 of a collection the local installation is (by default) synchronized
1101 to the status of the collection on the server, for both additions
1102 and removals.
1103 This means that if a package has been removed on the server (and
1105 thus has also been removed from the respective collection), "tlmgr"
1106 will remove the package in the local installation. This is called
1107 ``auto-remove'' and is announced as such when using the option
1108 "--list". This auto-removal can be suppressed using the option
1109 "--no-auto-remove" (not recommended, see option description).
1110 Analogously, if a package has been added to a collection on the
1112 server that is also installed locally, it will be added to the
1113 local installation. This is called ``auto-install'' and is
1114 announced as such when using the option "--list". This auto-
1115 installation can be suppressed using the option
1116 "--no-auto-install".
1117 An exception to the collection dependency checks (including the
1119 auto-installation of packages just mentioned) are those that have
1120 been ``forcibly removed'' by you, that is, you called "tlmgr remove
1121 --force" on them. (See the "remove" action documentation.) To
1122 reinstall any such forcibly removed packages use
1123 "--reinstall-forcibly-removed".
1124 If you want to exclude some packages from the current update run
1126 (e.g., due to a slow link), see the "--exclude" option below.
1127 --self
1129 Update "tlmgr" itself (that is, the infrastructure packages) if
1130 updates to it are present. On Windows this includes updates to the
1131 private Perl interpreter shipped inside TeX Live.
1132 If this option is given together with either "--all" or a list of
1134 packages, then "tlmgr" will be updated first and, if this update
1135 succeeds, the new version will be restarted to complete the rest of
1136 the updates.
1137 In short:
1139 tlmgr update --self # update infrastructure only
1141 tlmgr update --self --all # update infrastructure and all packages
1142 tlmgr update --force --all # update all packages but *not* infrastructure
1143 # ... this last at your own risk, not recommended!
1144 --dry-run
1146 Nothing is actually installed; instead, the actions to be performed
1147 are written to the terminal. This is a more detailed report than
1148 "--list".
1149 --list [pkg]
1151 Concisely list the packages which would be updated, newly
1152 installed, or removed, without actually changing anything. If
1153 "--all" is also given, all available updates are listed. If
1154 "--self" is given, but not "--all", only updates to the critical
1155 packages (tlmgr, texlive infrastructure, perl on Windows, etc.)
1156 are listed. If neither "--all" nor "--self" is given, and in
1157 addition no pkg is given, then "--all" is assumed (thus, "tlmgr
1158 update --list" is the same as "tlmgr update --list --all"). If
1159 neither "--all" nor "--self" is given, but specific package names
1160 are given, those packages are checked for updates.
1161 --exclude pkg
1163 Exclude pkg from the update process. If this option is given more
1164 than once, its arguments accumulate.
1165 An argument pkg excludes both the package pkg itself and all its
1167 related platform-specific packages pkg.ARCH. For example,
1168 tlmgr update --all --exclude a2ping
1170 will not update "a2ping", "a2ping.i386-linux", or any other
1172 "a2ping."ARCH package.
1173 If this option specifies a package that would otherwise be a
1175 candidate for auto-installation, auto-removal, or reinstallation of
1176 a forcibly removed package, "tlmgr" quits with an error message.
1177 Excludes are not supported in these circumstances.
1178 This option can also be set permanently in the tlmgr config file
1180 with the key "update-exclude".
1181 --no-auto-remove [pkg...]
1183 By default, "tlmgr" tries to remove packages which have disappeared
1184 on the server, as described above under "--all". This option
1185 prevents such removals, either for all packages (with "--all"), or
1186 for just the given pkg names. This can lead to an inconsistent TeX
1187 installation, since packages are not infrequently renamed or
1188 replaced by their authors. Therefore this is not recommend.
1189 --no-auto-install [pkg...]
1191 Under normal circumstances "tlmgr" will install packages which are
1192 new on the server, as described above under "--all". This option
1193 prevents any such automatic installation, either for all packages
1194 (with "--all"), or the given pkg names.
1195 Furthermore, after the "tlmgr" run using this has finished, the
1197 packages that would have been auto-installed will be considered as
1198 forcibly removed. So, if "foobar" is the only new package on the
1199 server, then
1200 tlmgr update --all --no-auto-install
1202 is equivalent to
1204 tlmgr update --all
1206 tlmgr remove --force foobar
1207 --reinstall-forcibly-removed
1209 Under normal circumstances "tlmgr" will not install packages that
1210 have been forcibly removed by the user; that is, removed with
1211 "remove --force", or whose installation was prohibited by
1212 "--no-auto-install" during an earlier update.
1213 This option makes "tlmgr" ignore the forcible removals and re-
1215 install all such packages. This can be used to completely
1216 synchronize an installation with the server's idea of what is
1217 available:
1218 tlmgr update --reinstall-forcibly-removed --all
1220 --backup
1222 --backupdir directory
1223 These two options control the creation of backups of packages
1224 before updating; that is, backup of packages as currently
1225 installed. If neither options is given, no backup will made. If
1226 "--backupdir" is given and specifies a writable directory then a
1227 backup will be made in that location. If only "--backup" is given,
1228 then a backup will be made to the directory previously set via the
1229 "option" action (see below). If both are given then a backup will
1230 be made to the specified directory.
1231 You can also set options via the "option" action to automatically
1233 make backups for all packages, and/or keep only a certain number of
1234 backups.
1235 "tlmgr" always makes a temporary backup when updating packages, in
1237 case of download or other failure during an update. In contrast,
1238 the purpose of this "--backup" option is to save a persistent
1239 backup in case the actual content of the update causes problems,
1240 e.g., introduces an TeX incompatibility.
1241 The "restore" action explains how to restore from a backup.
1243 --no-depends
1245 If you call for updating a package normally all depending packages
1246 will also be checked for updates and updated if necessary. This
1247 switch suppresses this behavior.
1248 --no-depends-at-all
1250 See above under install (and beware).
1251 --force
1253 Force update of normal packages, without updating "tlmgr" itself
1254 (unless the "--self" option is also given). Not recommended.
1255 Also, "update --list" is still performed regardless of this option.
1257 If the package on the server is older than the package already
1259 installed (e.g., if the selected mirror is out of date), "tlmgr" does
1260 not downgrade. Also, packages for uninstalled platforms are not
1261 installed.
1262 "tlmgr" saves a copy of the "texlive.tlpdb" file used for an update
1264 with a suffix representing the repository url, as in
1265 "tlpkg/texlive.tlpdb."long-hash-string. These can be useful for
1266 fallback information, but if you don't like them accumulating (e.g.,
1267 "mirror.ctan.org" resolves to many different hosts, each resulting in a
1268 possibly different hash), it's harmless to delete them.
1269
1271 "tlmgr" reads two configuration files: one is system-wide, in
1272 "TEXMFSYSCONFIG/tlmgr/config", and the other is user-specific, in
1273 "TEXMFCONFIG/tlmgr/config". The user-specific one is the default for
1274 the "conf tlmgr" action. (Run "kpsewhich -var-value=TEXMFSYSCONFIG" or
1275 "... TEXMFCONFIG ..." to see the actual directory names.)
1276 A few defaults corresponding to command-line options can be set in
1278 these configuration files. In addition, the system-wide file can
1279 contain a directive to restrict the allowed actions.
1280 In these config files, empty lines and lines starting with # are
1282 ignored. All other lines must look like:
1283 key = value
1285 where the spaces are optional but the "=" is required.
1287 The allowed keys are:
1289 "auto-remove", value 0 or 1 (default 1), same as command-line option.
1291 "gui-expertmode", value 0 or 1 (default 1). This switches between the
1292 full GUI and a simplified GUI with only the most common settings.
1293 "gui-lang" llcode, with a language code value as with the command-line
1294 option.
1295 "no-checksums", value 0 or 1 (default 0, see below).
1296 "persistent-downloads", value 0 or 1 (default 1), same as command-line
1297 option.
1298 "require-verification", value 0 or 1 (default 0), same as command-line
1299 option.
1300 "update-exclude", value: comma-separated list of packages (no space
1301 allowed). Same as the command line option "--exclude" for the action
1302 "update".
1303 "verify-downloads", value 0 or 1 (default 1), same as command-line
1304 option.
1305 The system-wide config file can contain one additional key:
1307 "allowed-actions" action1 [,action,...] The value is a comma-separated
1309 list of "tlmgr" actions which are allowed to be executed when "tlmgr"
1310 is invoked in system mode (that is, without "--usermode").
1311 This allows distributors to include the "tlmgr" in their packaging,
1312 but allow only a restricted set of actions that do not interfere
1313 with their distro package manager. For native TeX Live
1314 installations, it doesn't make sense to set this.
1315 The "no-checksums" key needs more explanation. By default, package
1317 checksums computed and stored on the server (in the TLPDB) are compared
1318 to checksums computed locally after downloading. "no-checksums"
1319 disables this process.
1320 The checksum algorithm is SHA-512. Your system must have one of
1322 (looked for in this order) the Perl "Digest::SHA" module, the "openssl"
1323 program (<https://openssl.org>), the "sha512sum" program (from GNU
1324 Coreutils, <https://www.gnu.org/software/coreutils>), or finally the
1325 "shasum" program (just to support old Macs). If none of these are
1326 available, a warning is issued and "tlmgr" proceeds without checking
1327 checksums. (Incidentally, other SHA implementations, such as the pure
1328 Perl and pure Lua modules, are much too slow to be usable in our
1329 context.) "no-checksums" avoids the warning.
1330
1332 "tlmgr" and "install-tl" perform cryptographic verification if
1333 possible. If verification is performed and successful, the programs
1334 report "(verified)" after loading the TLPDB; otherwise, they report
1335 "(not verified)". But either way, by default the installation and/or
1336 updates proceed normally.
1337 If a program named "gpg" is available (that is, found in "PATH"), by
1339 default cryptographic signatures will be checked: we require the main
1340 repository be signed, but not any additional repositories. If "gpg" is
1341 not available, by default signatures are not checked and no
1342 verification is carried out, but "tlmgr" still proceeds normally.
1343 The behavior of the verification can be controlled by the command line
1345 and config file option "verify-repo" which takes one of the following
1346 values: "none", "main", or "all". With "none", no verification
1347 whatsoever is attempted. With "main" (the default) verification is
1348 required only for the main repository, and only if "gpg" is available;
1349 though attempted for all, missing signatures of subsidiary repositories
1350 will not result in an error. Finally, in the case of "all", "gpg" must
1351 be available and all repositories need to be signed.
1352 In all cases, if a signature is checked and fails to verify, an error
1354 is raised.
1355 Cryptographic verification requires checksum checking (described just
1357 above) to succeed, and a working GnuPG ("gpg") program (see below for
1358 search method). Then, unless cryptographic verification has been
1359 disabled, a signature file ("texlive.tlpdb.*.asc") of the checksum file
1360 is downloaded and the signature verified. The signature is created by
1361 the TeX Live Distribution GPG key 0x0D5E5D9106BAB6BC, which in turn is
1362 signed by Karl Berry's key 0x0716748A30D155AD and Norbert Preining's
1363 key 0x6CACA448860CDC13. All of these keys are obtainable from the
1364 standard key servers.
1365 Additional trusted keys can be added using the "key" action.
1367 Configuration of GnuPG invocation
1369 The executable used for GnuPG is searched as follows: If the
1370 environment variable "TL_GNUPG" is set, it is tested and used;
1371 otherwise "gpg" is checked; finally "gpg2" is checked.
1372 Further adaptation of the "gpg" invocation can be made using the two
1374 environment variables "TL_GNUPGHOME", which is passed to "gpg" as the
1375 value for "--homedir", and "TL_GNUPGARGS", which replaces the default
1376 options "--no-secmem-warning --no-permission-warning".
1377
1379 "tlmgr" provides a restricted way, called ``user mode'', to manage
1380 arbitrary texmf trees in the same way as the main installation. For
1381 example, this allows people without write permissions on the
1382 installation location to update/install packages into a tree of their
1383 own.
1384 "tlmgr" is switched into user mode with the command line option
1386 "--usermode". It does not switch automatically, nor is there any
1387 configuration file setting for it. Thus, this option has to be
1388 explicitly given every time user mode is to be activated.
1389 This mode of "tlmgr" works on a user tree, by default the value of the
1391 "TEXMFHOME" variable. This can be overridden with the command line
1392 option "--usertree". In the following when we speak of the user tree
1393 we mean either "TEXMFHOME" or the one given on the command line.
1394 Not all actions are allowed in user mode; "tlmgr" will warn you and not
1396 carry out any problematic actions. Currently not supported (and
1397 probably will never be) is the "platform" action. The "gui" action is
1398 currently not supported, but may be in a future release.
1399 Some "tlmgr" actions don't need any write permissions and thus work the
1401 same in user mode and normal mode. Currently these are: "check",
1402 "help", "list", "print-platform", "print-platform-info", "search",
1403 "show", "version".
1404 On the other hand, most of the actions dealing with package management
1406 do need write permissions, and thus behave differently in user mode, as
1407 described below: "install", "update", "remove", "option", "paper",
1408 "generate", "backup", "restore", "uninstall", "symlinks".
1409 Before using "tlmgr" in user mode, you have to set up the user tree
1411 with the "init-usertree" action. This creates usertree"/web2c" and
1412 usertree"/tlpkg/tlpobj", and a minimal usertree"/tlpkg/texlive.tlpdb".
1413 At that point, you can tell "tlmgr" to do the (supported) actions by
1414 adding the "--usermode" command line option.
1415 In user mode the file usertree"/tlpkg/texlive.tlpdb" contains only the
1417 packages that have been installed into the user tree using "tlmgr",
1418 plus additional options from the ``virtual'' package
1419 "00texlive.installation" (similar to the main installation's
1420 "texlive.tlpdb").
1421 All actions on packages in user mode can only be carried out on
1423 packages that are known as "relocatable". This excludes all packages
1424 containing executables and a few other core packages. Of the 2500 or
1425 so packages currently in TeX Live the vast majority are relocatable and
1426 can be installed into a user tree.
1427 Description of changes of actions in user mode:
1429 User mode install
1431 In user mode, the "install" action checks that the package and all
1432 dependencies are all either relocated or already installed in the
1433 system installation. If this is the case, it unpacks all containers to
1434 be installed into the user tree (to repeat, that's either "TEXMFHOME"
1435 or the value of "--usertree") and add the respective packages to the
1436 user tree's "texlive.tlpdb" (creating it if need be).
1437 Currently installing a collection in user mode installs all dependent
1439 packages, but in contrast to normal mode, does not install dependent
1440 collections. For example, in normal mode "tlmgr install
1441 collection-context" would install "collection-basic" and other
1442 collections, while in user mode, only the packages mentioned in
1443 "collection-context" are installed.
1444 If a package shipping map files is installed in user mode, a backup of
1446 the user's "updmap.cfg" in "USERTREE/web2c/" is made, and then this
1447 file regenerated from the list of installed packages.
1448 User mode backup, restore, remove, update
1450 In user mode, these actions check that all packages to be acted on are
1451 installed in the user tree before proceeding; otherwise, they behave
1452 just as in normal mode.
1453 User mode generate, option, paper
1455 In user mode, these actions operate only on the user tree's
1456 configuration files and/or "texlive.tlpdb". creates configuration
1457 files in user tree
1458
1460 The main TeX Live repository contains a vast array of packages.
1461 Nevertheless, additional local repositories can be useful to provide
1462 locally-installed resources, such as proprietary fonts and house
1463 styles. Also, alternative package repositories distribute packages
1464 that cannot or should not be included in TeX Live, for whatever reason.
1465 The simplest and most reliable method is to temporarily set the
1467 installation source to any repository (with the "-repository" or
1468 "option repository" command line options), and perform your operations.
1469 When you are using multiple repositories over a sustained length of
1471 time, however, explicitly switching between them becomes inconvenient.
1472 Thus, it's possible to tell "tlmgr" about additional repositories you
1473 want to use. The basic command is "tlmgr repository add". The rest of
1474 this section explains further.
1475 When using multiple repositories, one of them has to be set as the main
1477 repository, which distributes most of the installed packages. When you
1478 switch from a single repository installation to a multiple repository
1479 installation, the previous sole repository will be set as the main
1480 repository.
1481 By default, even if multiple repositories are configured, packages are
1483 still only installed from the main repository. Thus, simply adding a
1484 second repository does not actually enable installation of anything
1485 from there. You also have to specify which packages should be taken
1486 from the new repository, by specifying so-called ``pinning'' rules,
1487 described next.
1488 Pinning
1490 When a package "foo" is pinned to a repository, a package "foo" in any
1491 other repository, even if it has a higher revision number, will not be
1492 considered an installable candidate.
1493 As mentioned above, by default everything is pinned to the main
1495 repository. Let's now go through an example of setting up a second
1496 repository and enabling updates of a package from it.
1497 First, check that we have support for multiple repositories, and have
1499 only one enabled (as is the case by default):
1500 $ tlmgr repository list
1502 List of repositories (with tags if set):
1503 /var/www/norbert/tlnet
1504 Ok. Let's add the "tlcontrib" repository (this is a real repository
1506 hosted at <http://contrib.texlive.info>) with the tag "tlcontrib":
1507 $ tlmgr repository add http://contrib.texlive.info/current tlcontrib
1509 Check the repository list again:
1511 $ tlmgr repository list
1513 List of repositories (with tags if set):
1514 http://contrib.texlive.info/current (tlcontrib)
1515 /var/www/norbert/tlnet (main)
1516 Now we specify a pinning entry to get the package "classico" from
1518 "tlcontrib":
1519 $ tlmgr pinning add tlcontrib classico
1521 Check that we can find "classico":
1523 $ tlmgr show classico
1525 package: classico
1526 ...
1527 shortdesc: URW Classico fonts
1528 ...
1529 - install "classico":
1531 $ tlmgr install classico
1533 tlmgr: package repositories:
1534 ...
1535 [1/1, ??:??/??:??] install: classico @tlcontrib [737k]
1536 In the output here you can see that the "classico" package has been
1538 installed from the "tlcontrib" repository (@tlcontrib).
1539 Finally, "tlmgr pinning" also supports removing certain or all packages
1541 from a given repository:
1542 $ tlmgr pinning remove tlcontrib classico # remove just classico
1544 $ tlmgr pinning remove tlcontrib --all # take nothing from tlcontrib
1545 A summary of the "tlmgr pinning" actions is given above.
1547
1549 The graphical user interface for "tlmgr" requires Perl/Tk
1550 <https://search.cpan.org/search?query=perl%2Ftk>. For Unix-based
1551 systems Perl/Tk (as well as Perl of course) has to be installed outside
1552 of TL. <https://tug.org/texlive/distro.html#perltk> has a list of
1553 invocations for some distros. For Windows the necessary modules are no
1554 longer shipped within TeX Live, so you'll have to have an external Perl
1555 available that includes them.
1556 We are talking here about the GUI built into tlmgr itself, not about
1558 the other tlmgr GUIs, which are: tlshell (Tcl/Tk-based), tlcockpit
1559 (Java-based) and, only on Macs, TeX Live Utility. These are invoked as
1560 separate programs.
1561 The GUI mode of tlmgr is started with the invocation "tlmgr gui";
1563 assuming Tk is loadable, the graphical user interface will be shown.
1564 The main window contains a menu bar, the main display, and a status
1565 area where messages normally shown on the console are displayed.
1566 Within the main display there are three main parts: the "Display
1568 configuration" area, the list of packages, and the action buttons.
1569 Also, at the top right the currently loaded repository is shown; this
1571 also acts as a button and when clicked will try to load the default
1572 repository. To load a different repository, see the "tlmgr" menu item.
1573 Finally, the status area at the bottom of the window gives additional
1575 information about what is going on.
1576 Main display
1578 Display configuration area
1579 The first part of the main display allows you to specify (filter) which
1581 packages are shown. By default, all are shown. Changes here are
1582 reflected right away.
1583 Status
1585 Select whether to show all packages (the default), only those
1586 installed, only those not installed, or only those with update
1587 available.
1588 Category
1590 Select which categories are shown: packages, collections, and/or
1591 schemes. These are briefly explained in the "DESCRIPTION" section
1592 above.
1593 Match
1595 Select packages matching for a specific pattern. By default, this
1596 searches both descriptions and filenames. You can also select a
1597 subset for searching.
1598 Selection
1600 Select packages to those selected, those not selected, or all.
1601 Here, ``selected'' means that the checkbox in the beginning of the
1602 line of a package is ticked.
1603 Display configuration buttons
1605 To the right there are three buttons: select all packages, select
1606 none (a.k.a. deselect all), and reset all these filters to the
1607 defaults, i.e., show all available.
1608 Package list area
1610 The second are of the main display lists all installed packages. If a
1612 repository is loaded, those that are available but not installed are
1613 also listed.
1614 Double clicking on a package line pops up an informational window with
1616 further details: the long description, included files, etc.
1617 Each line of the package list consists of the following items:
1619 a checkbox
1621 Used to select particular packages; some of the action buttons (see
1622 below) work only on the selected packages.
1623 package name
1625 The name (identifier) of the package as given in the database.
1626 local revision (and version)
1628 If the package is installed the TeX Live revision number for the
1629 installed package will be shown. If there is a catalogue version
1630 given in the database for this package, it will be shown in
1631 parentheses. However, the catalogue version, unlike the TL
1632 revision, is not guaranteed to reflect what is actually installed.
1633 remote revision (and version)
1635 If a repository has been loaded the revision of the package in the
1636 repository (if present) is shown. As with the local column, if a
1637 catalogue version is provided it will be displayed. And also as
1638 with the local column, the catalogue version may be stale.
1639 short description
1641 The short description of the package.
1642 Main display action buttons
1644 Below the list of packages are several buttons:
1646 Update all installed
1648 This calls "tlmgr update --all", i.e., tries to update all
1649 available packages. Below this button is a toggle to allow
1650 reinstallation of previously removed packages as part of this
1651 action.
1652 The other four buttons only work on the selected packages, i.e.,
1654 those where the checkbox at the beginning of the package line is
1655 ticked.
1656 Update
1658 Update only the selected packages.
1659 Install
1661 Install the selected packages; acts like "tlmgr install", i.e.,
1662 also installs dependencies. Thus, installing a collection installs
1663 all its constituent packages.
1664 Remove
1666 Removes the selected packages; acts like "tlmgr remove", i.e., it
1667 will also remove dependencies of collections (but not dependencies
1668 of normal packages).
1669 Backup
1671 Makes a backup of the selected packages; acts like "tlmgr backup".
1672 This action needs the option "backupdir" set (see "Options -"
1673 General>).
1674 Menu bar
1676 The following entries can be found in the menu bar:
1677 "tlmgr" menu
1679 The items here load various repositories: the default as specified
1680 in the TeX Live database, the default network repository, the
1681 repository specified on the command line (if any), and an
1682 arbitrarily manually-entered one. Also has the so-necessary "quit"
1683 operation.
1684 "Options menu"
1686 Provides access to several groups of options: "Paper"
1687 (configuration of default paper sizes), "Platforms" (only on Unix,
1688 configuration of the supported/installed platforms), "GUI Language"
1689 (select language used in the GUI interface), and "General"
1690 (everything else).
1691 Several toggles are also here. The first is "Expert options",
1693 which is set by default. If you turn this off, the next time you
1694 start the GUI a simplified screen will be shown that display only
1695 the most important functionality. This setting is saved in the
1696 configuration file of "tlmgr"; see "CONFIGURATION FILE FOR TLMGR"
1697 for details.
1698 The other toggles are all off by default: for debugging output, to
1700 disable the automatic installation of new packages, and to disable
1701 the automatic removal of packages deleted from the server. Playing
1702 with the choices of what is or isn't installed may lead to an
1703 inconsistent TeX Live installation; e.g., when a package is
1704 renamed.
1705 "Actions menu"
1707 Provides access to several actions: update the filename database
1708 (aka "ls-R", "mktexlsr", "texhash"), rebuild all formats
1709 ("fmtutil-sys --all"), update the font map database ("updmap-sys"),
1710 restore from a backup of a package, and use of symbolic links in
1711 system directories (not on Windows).
1712 The final action is to remove the entire TeX Live installation
1714 (also not on Windows).
1715 "Help menu"
1717 Provides access to the TeX Live manual (also on the web at
1718 <https://tug.org/texlive/doc.html>) and the usual ``About'' box.
1719 GUI options
1721 Some generic Perl/Tk options can be specified with "tlmgr gui" to
1722 control the display:
1723 "-background" color
1725 Set background color.
1726 "-font "" fontname fontsize """
1728 Set font, e.g., "tlmgr gui -font "helvetica 18"". The argument to
1729 "-font" must be quoted, i.e., passed as a single string.
1730 "-foreground" color
1732 Set foreground color.
1733 "-geometry" geomspec
1735 Set the X geometry, e.g., "tlmgr gui -geometry 1024x512-0+0"
1736 creates the window of (approximately) the given size in the upper-
1737 right corner of the display.
1738 "-xrm" xresource
1740 Pass the arbitrary X resource string xresource.
1741 A few other obscure options are recognized but not mentioned here. See
1743 the Perl/Tk documentation (<https://search.cpan.org/perldoc?Tk>) for
1744 the complete list, and any X documentation for general information.
1745
1747 With the "--machine-readable" option, "tlmgr" writes to stdout in the
1748 fixed line-oriented format described here, and the usual informational
1749 messages for human consumption are written to stderr (normally they are
1750 written to stdout). The idea is that a program can get all the
1751 information it needs by reading stdout.
1752 Currently this option only applies to the update, install, and "option"
1754 actions.
1755 Machine-readable "update" and "install" output
1757 The output format is as follows:
1758 fieldname "\t" value
1760 ...
1761 "end-of-header"
1762 pkgname status localrev serverrev size runtime esttot
1763 ...
1764 "end-of-updates"
1765 other output from post actions, not in machine readable form
1766 The header section currently has two fields: "location-url" (the
1768 repository source from which updates are being drawn), and
1769 "total-bytes" (the total number of bytes to be downloaded).
1770 The localrev and serverrev fields for each package are the revision
1772 numbers in the local installation and server repository, respectively.
1773 The size field is the number of bytes to be downloaded, i.e., the size
1774 of the compressed tar file for a network installation, not the unpacked
1775 size. The runtime and esttot fields are only present for updated and
1776 auto-install packages, and contain the currently passed time since
1777 start of installation/updates and the estimated total time.
1778 Line endings may be either LF or CRLF depending on the current
1780 platform.
1781 "location-url" location
1783 The location may be a url (including "file:///foo/bar/..."), or a
1784 directory name ("/foo/bar"). It is the package repository from
1785 which the new package information was drawn.
1786 "total-bytes" count
1788 The count is simply a decimal number, the sum of the sizes of all
1789 the packages that need updating or installing (which are listed
1790 subsequently).
1791 Then comes a line with only the literal string "end-of-header".
1793 Each following line until a line with literal string "end-of-updates"
1795 reports on one package. The fields on each line are separated by a
1796 tab. Here are the fields.
1797 pkgname
1799 The TeX Live package identifier, with a possible platform suffix
1800 for executables. For instance, "pdftex" and "pdftex.i386-linux"
1801 are given as two separate packages, one on each line.
1802 status
1804 The status of the package update. One character, as follows:
1805 "d" The package was removed on the server.
1807 "f" The package was removed in the local installation, even
1809 though a collection depended on it. (E.g., the user ran
1810 "tlmgr remove --force".)
1811 "u" Normal update is needed.
1813 "r" Reversed non-update: the locally-installed version is newer
1815 than the version on the server.
1816 "a" Automatically-determined need for installation, the package
1818 is new on the server and is (most probably) part of an
1819 installed collection.
1820 "i" Package will be installed and isn't present in the local
1822 installation (action install).
1823 "I" Package is already present but will be reinstalled (action
1825 install).
1826 localrev
1828 The revision number of the installed package, or "-" if it is not
1829 present locally.
1830 serverrev
1832 The revision number of the package on the server, or "-" if it is
1833 not present on the server.
1834 size
1836 The size in bytes of the package on the server. The sum of all the
1837 package sizes is given in the "total-bytes" header field mentioned
1838 above.
1839 runtime
1841 The run time since start of installations or updates.
1842 esttot
1844 The estimated total time.
1845 Machine-readable "option" output
1847 The output format is as follows:
1848 key "\t" value
1850 If a value is not saved in the database the string "(not set)" is
1852 shown.
1853 If you are developing a program that uses this output, and find that
1855 changes would be helpful, do not hesitate to write the mailing list.
1856
1858 "tlmgr" uses many of the standard TeX environment variables, as
1859 reported by, e.g., "tlmgr conf" ("conf").
1860 In addition, for ease in scripting and debugging, "tlmgr" looks for the
1862 following environment variables. These are not of interest for normal
1863 user installations.
1864 "TEXLIVE_COMPRESSOR"
1866 This option allows selecting a different compressor program for
1867 backups and intermediate rollback containers. The order of
1868 selection is:
1869 1. If the environment variable "TEXLIVE_COMPRESSOR" is
1871 defined, use it; abort if it doesn't work. Possible values:
1872 "lz4", "gzip", "xz". The necessary options are added
1873 internally.
1874 2. If lz4 is available (either from the system or TL) and
1876 working, use that.
1877 3. If gzip is available (from the system) and working, use
1879 that.
1880 4. If xz is available (either from the system or TL) and
1882 working, use that.
1883 lz4 and gzip are much faster in creating tlmgr's local backups.
1885 The unconditional use of xz for the tlnet containers is unaffected,
1886 to minimize download sizes.
1887 "TEXLIVE_DOWNLOADER"
1889 "TL_DOWNLOAD_PROGRAM"
1890 "TL_DOWNLOAD_ARGS"
1891 These options allow selecting different download programs then the
1892 ones automatically selected by the installer. The order of
1893 selection is:
1894 1. If the environment variable "TEXLIVE_DOWNLOADER" is
1896 defined, use it; abort if the specified program doesn't
1897 work. Possible values: "lwp", "curl", "wget". The necessary
1898 options are added internally.
1899 2. If the environment variable "TL_DOWNLOAD_PROGRAM" is
1901 defined (can be any value), use it together with
1902 "TL_DOWNLOAD_ARGS"; abort if it doesn't work.
1903 3. If LWP is available and working, use that (by far the most
1905 efficient method, as it supports persistent downloads).
1906 4. If curl is available (from the system) and working, use
1908 that.
1909 5. If wget is available (either from the system or TL) and
1911 working, use that.
1912 TL provides "wget" binaries for platforms where necessary, so some
1914 download method should always be available.
1915 "TEXLIVE_PREFER_OWN"
1917 By default, compression and download programs provided by the
1918 system, i.e., found along "PATH" are preferred over those shipped
1919 with TeX Live.
1920 This can create problems with systems that are too old, and so can
1922 be overridden by setting the environment variable
1923 "TEXLIVE_PREFER_OWN" to 1. In this case, executables shipped with
1924 TL will be preferred.
1925 Extra compression/download programs not provided by TL, such as
1927 gzip, lwp, and curl, are still checked for on the system and used
1928 if available, per the above. "TEXLIVE_PREFER_OWN" only applies when
1929 the program being checked for is shipped with TL, namely the lz4
1930 and xz compressors and wget downloader.
1931 Exception: on Windows, the "tar.exe" shipped with TL is always
1933 used, regardless of any setting.
1934
1936 This script and its documentation were written for the TeX Live
1937 distribution (<https://tug.org/texlive>) and both are licensed under
1938 the GNU General Public License Version 2 or later.
1939 $Id: tlmgr.pl 50796 2019-04-05 22:43:08Z karl $
1941perl v5.28.1 2019-04-05 TLMGR(1)