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.
42 Caveat: "mirror.ctan.org" resolves to many different hosts, and
44 they are not perfectly synchronized; we recommend updating only
45 daily (at most), and not more often. You can choose a particular
46 mirror if problems; the list of all CTAN mirrors with the status of
47 each is at <https://ctan.org/mirrors/mirmon>.
48 "tlmgr update --list"
50 Report what would be updated without actually updating anything.
51 "tlmgr update --all"
53 Make your local TeX installation correspond to what is in the
54 package repository (typically useful when updating from CTAN).
55 "tlmgr info" what
57 Display detailed information about a package what, such as the
58 installation status and description, of searches for what in all
59 packages.
60 For all the capabilities and details of "tlmgr", please read the
62 following voluminous information.
63
65 The following options to "tlmgr" are global options, not specific to
66 any action. All options, whether global or action-specific, can be
67 given anywhere on the command line, and in any order. The first non-
68 option argument will be the main action. In all cases, "--"option and
69 "-"option are equivalent, and an "=" is optional between an option name
70 and its value.
71 --repository url|path
73 Specify the package repository from which packages should be
74 installed or updated, either a local directory or network location,
75 as below. This overridesthe default package repository found in the
76 installation's TeX Live Package Database (a.k.a. the TLPDB, which
77 is given entirely in the file "tlpkg/texlive.tlpdb").
78 This "--repository" option changes the location only for the
80 current run; to make a permanent change, use "option repository"
81 (see the "option" action).
82 As an example, you can choose a particular CTAN mirror with
84 something like this:
85 -repository http://ctan.example.org/its/ctan/dir/systems/texlive/tlnet
87 Of course a real hostname and its particular top-level CTAN
89 directory have to be specified. The list of CTAN mirrors is
90 available at <https://ctan.org/mirrors/mirmon>.
91 Here's an example of using a local directory:
93 -repository /local/TL/repository
95 For backward compatibility and convenience, "--location" and
97 "--repo" are accepted as aliases for this option.
98 Locations can be specified as any of the following:
100 "/some/local/dir"
102 "file:/some/local/dir"
103 Equivalent ways of specifying a local directory.
104 "ctan"
106 "http://mirror.ctan.org/systems/texlive/tlnet"
107 Pick a CTAN mirror automatically, trying for one that is both
108 nearby and up-to-date. The chosen mirror is used for the entire
109 download. The bare "ctan" is merely an alias for the full url.
110 (See <https://ctan.org> for more about CTAN and its mirrors.)
111 "http://server/path/to/tlnet"
113 Standard HTTP. If the (default) LWP method is used, persistent
114 connections are supported. TL can also use "curl" or "wget" to
115 do the downloads, or an arbitrary user-specified program, as
116 described in the "tlmgr" documentation
117 (<https://tug.org/texlive/doc/tlmgr.html#ENVIRONMENT-VARIABLES>).
118 "https://server/path/to/tlnet"
120 Again, if the (default) LWP method is used, this supports
121 persistent connections. Unfortunately, some versions of "wget"
122 and "curl" do not support https, and even when "wget" supports
123 https, certificates may be rejected even when the certificate
124 is fine, due to a lack of local certificate roots. The simplest
125 workaround for this problem is to use http or ftp.
126 "ftp://server/path/to/tlnet"
128 If the (default) LWP method is used, persistent connections are
129 supported.
130 "user@machine:/path/to/tlnet"
132 "scp://user@machine/path/to/tlnet"
133 "ssh://user@machine/path/to/tlnet"
134 These forms are equivalent; they all use "scp" to transfer
135 files. Using "ssh-agent" is recommended. (Info:
136 <https://en.wikipedia.org/wiki/OpenSSH>,
137 <https://en.wikipedia.org/wiki/Ssh-agent>.)
138 If the repository is on the network, trailing "/" characters and/or
140 trailing "/tlpkg" and/or "/archive" components are ignored.
141 --gui [action]
143 Two notable GUI front-ends for "tlmgr", "tlshell" and "tlcockpit",
144 are started up as separate programs; see their own documentation.
145 "tlmgr" itself has a graphical interface as well as the command
147 line interface. You can give the option to invoke it, "--gui",
148 together with an action to be brought directly into the respective
149 screen of the GUI. For example, running
150 tlmgr --gui update
152 starts you directly at the update screen. If no action is given,
154 the GUI will be started at the main screen. See "GUI FOR TLMGR".
155 However, the native GUI requires Perl/TK, which is no longer
157 included in TeX Live's Perl distribution for Windows. You may find
158 "tlshell" or "tlcockpit" easier to work with.
159 --gui-lang llcode
161 By default, the GUI tries to deduce your language from the
162 environment (on Windows via the registry, on Unix via
163 "LC_MESSAGES"). If that fails you can select a different language
164 by giving this option with a language code (based on ISO 639-1).
165 Currently supported (but not necessarily completely translated)
166 are: English (en, default), Czech (cs), German (de), French (fr),
167 Italian (it), Japanese (ja), Dutch (nl), Polish (pl),
168 Brazilian Portuguese (pt_BR), Russian (ru), Slovak (sk),
169 Slovenian (sl), Serbian (sr), Ukrainian (uk), Vietnamese (vi),
170 simplified Chinese (zh_CN), and traditional Chinese (zh_TW).
171 tlshell shares its message catalog with tlmgr.
173 --debug-translation
175 In GUI mode, this switch tells "tlmgr" to report any untranslated
176 (or missing) messages to standard error. This can help translators
177 to see what remains to be done.
178 --machine-readable
180 Instead of the normal output intended for human consumption, write
181 (to standard output) a fixed format more suitable for machine
182 parsing. See the "MACHINE-READABLE OUTPUT" section below.
183 --no-execute-actions
185 Suppress the execution of the execute actions as defined in the
186 tlpsrc files. Documented only for completeness, as this is only
187 useful in debugging.
188 --package-logfile file
190 "tlmgr" logs all package actions (install, remove, update, failed
191 updates, failed restores) to a separate log file, by default
192 "TEXMFSYSVAR/web2c/tlmgr.log". This option allows you to specify a
193 different file for the log.
194 --pause
196 This option makes "tlmgr" wait for user input before exiting.
197 Useful on Windows to avoid disappearing command windows.
198 --persistent-downloads
200 --no-persistent-downloads
201 For network-based installations, this option (on by default) makes
202 "tlmgr" try to set up a persistent connection (using the "LWP" Perl
203 module). The idea is to open and reuse only one connection per
204 session between your computer and the server, instead of initiating
205 a new download for each package.
206 If this is not possible, "tlmgr" will fall back to using "wget".
208 To disable these persistent connections, use
209 "--no-persistent-downloads".
210 --pin-file
212 Change the pinning file location from
213 "TEXMFLOCAL/tlpkg/pinning.txt" (see "Pinning" below). Documented
214 only for completeness, as this is only useful in debugging.
215 --usermode
217 Activates user mode for this run of "tlmgr"; see "USER MODE" below.
218 --usertree dir
220 Uses dir for the tree in user mode; see "USER MODE" below.
221 --verify-repo=[none|main|all]
223 Defines the level of verification done: If "none" is specified, no
224 verification whatsoever is done. If "main" is given and a working
225 GnuPG ("gpg") binary is available, all repositories are checked,
226 but only the main repository is required to be signed. If "all" is
227 given, then all repositories need to be signed. See "CRYPTOGRAPHIC
228 VERIFICATION" below for details.
229 The standard options for TeX Live programs are also accepted:
231 "--help/-h/-?", "--version", "-q" (no informational messages), "-v"
232 (debugging messages, can be repeated). For the details about these,
233 see the "TeXLive::TLUtils" documentation.
234 The "--version" option shows version information about the TeX Live
236 release and about the "tlmgr" script itself. If "-v" is also given,
237 revision number for the loaded TeX Live Perl modules are shown, too.
238
240 help
241 Display this help information and exit (same as "--help", and on the
242 web at <https://tug.org/texlive/doc/tlmgr.html>). Sometimes the
243 "perldoc" and/or "PAGER" programs on the system have problems,
244 resulting in control characters being literally output. This can't
245 always be detected, but you can set the "NOPERLDOC" environment
246 variable and "perldoc" will not be used.
247 version
249 Gives version information (same as "--version").
250 If "-v" has been given the revisions of the used modules are reported,
252 too.
253 backup
255 backup [option...] --all
256 backup [option...] pkg...
257 If the "--clean" option is not specified, this action makes a
258 backup of the given packages, or all packages given "--all". These
259 backups are saved to the value of the "--backupdir" option, if that
260 is an existing and writable directory. If "--backupdir" is not
261 given, the "backupdir" option setting in the TLPDB is used, if
262 present. If both are missing, no backups are made. (The installer
263 sets "backupdir" to ".../tlpkg/backups", under the TL root
264 installation directory, so it is usually defined; see the "option"
265 description for more information.)
266 If the "--clean" option is specified, backups are pruned (removed)
268 instead of saved. The optional integer value N may be specified to
269 set the number of backups that will be retained when cleaning. If
270 "N" is not given, the value of the "autobackup" option is used. If
271 both are missing, an error is issued. For more details of backup
272 pruning, see the "option" action.
273 Options:
275 --backupdir directory
277 Overrides the "backupdir" option setting in the TLPDB. The
278 directory argument is required and must specify an existing,
279 writable directory where backups are to be placed.
280 --all
282 If "--clean" is not specified, make a backup of all packages in
283 the TeX Live installation; this will take quite a lot of space
284 and time. If "--clean" is specified, all packages are pruned.
285 --clean[=N]
287 Instead of making backups, prune the backup directory of old
288 backups, as explained above. The optional integer argument N
289 overrides the "autobackup" option set in the TLPDB. You must
290 use "--all" or a list of packages together with this option, as
291 desired.
292 --dry-run
294 Nothing is actually backed up or removed; instead, the actions
295 to be performed are written to the terminal.
296 candidates pkg
298 Shows the available candidate repositories for package pkg. See
299 "MULTIPLE REPOSITORIES" below.
300 check [option...] [depends|executes|files|runfiles|texmfdbs|all]
302 Execute one (or all) check(s) of the consistency of the installation.
303 If no problems are found, there will be no output. (To get a view of
304 what is being done, run "tlmgr -v check".)
305 depends
307 Lists those packages which occur as dependencies in an installed
308 collection, but are themselves not installed, and those packages
309 which are not contained in any collection.
310 If you call "tlmgr check collections" this test will be carried out
312 instead since former versions for "tlmgr" called it that way.
313 executes
315 Check that the files referred to by "execute" directives in the TeX
316 Live Database are present.
317 files
319 Checks that all files listed in the local TLPDB ("texlive.tlpdb")
320 are actually present, and lists those missing.
321 runfiles
323 List those filenames that are occurring more than one time in the
324 runfiles sections, except for known duplicates.
325 texmfdbs
327 Checks related to the "ls-R" files. If you have defined new trees,
328 or changed the "TEXMF" or "TEXMFDBS" variables, it can't hurt to
329 run this. It checks that:
330 - all items in "TEXMFDBS" have the "!!" prefix.
332 - all items in "TEXMFBDS" have an "ls-R" file (if they exist at
333 all).
334 - all items in "TEXMF" with "!!" are listed in "TEXMFDBS".
335 - all items in "TEXMF" with an "ls-R" file are listed in
336 "TEXMFDBS".
337 Options:
339 --use-svn
341 Use the output of "svn status" instead of listing the files; for
342 checking the TL development repository. (This is run nightly.)
343 conf
345 conf [texmf|tlmgr|updmap [--conffile file] [--delete] [key [value]]]
346 conf auxtrees [--conffile file] [show|add|remove] [value]
347 With only "conf", show general configuration information for TeX
348 Live, including active configuration files, path settings, and
349 more. This is like running "texconfig conf", but works on all
350 supported platforms.
351 With one of "conf texmf", "conf tlmgr", or "conf updmap", shows all
353 key/value pairs (i.e., all settings) as saved in "ROOT/texmf.cnf",
354 the user-specific "tlmgr" configuration file (see below), or the
355 first found (via "kpsewhich") "updmap.cfg" file, respectively.
356 If key is given in addition, shows the value of only that key in
358 the respective file. If option --delete is also given, the value
359 in the given configuration file is entirely removed (not just
360 commented out).
361 If value is given in addition, key is set to value in the
363 respective file. No error checking is done!
364 The "PATH" value shown by "conf" is as used by "tlmgr". The
366 directory in which the "tlmgr" executable is found is automatically
367 prepended to the PATH value inherited from the environment.
368 Here is a practical example of changing configuration values. If
370 the execution of (some or all) system commands via "\write18" was
371 left enabled during installation, you can disable it afterwards:
372 tlmgr conf texmf shell_escape 0
374 The subcommand "auxtrees" allows adding and removing arbitrary
376 additional texmf trees, completely under user control. "auxtrees
377 show" shows the list of additional trees, "auxtrees add" tree adds
378 a tree to the list, and "auxtrees remove" tree removes a tree from
379 the list (if present). The trees should not contain an "ls-R" file
380 (or files will not be found if the "ls-R" becomes stale). This
381 works by manipulating the Kpathsea variable "TEXMFAUXTREES", in (by
382 default) "ROOT/texmf.cnf". Example:
383 tlmgr conf auxtrees add /quick/test/tree
385 tlmgr conf auxtrees remove /quick/test/tree
386 In all cases the configuration file can be explicitly specified via
388 the option "--conffile" file, e.g., if you don't want to change the
389 system-wide configuration.
390 Warning: The general facility for changing configuration values is
392 here, but tinkering with settings in this way is strongly
393 discouraged. Again, no error checking on either keys or values is
394 done, so any sort of breakage is possible.
395 dump-tlpdb [option...] [--json]
397 Dump complete local or remote TLPDB to standard output, as-is. The
398 output is analogous to the "--machine-readable" output; see "MACHINE-
399 READABLE OUTPUT" section.
400 Options:
402 --local
404 Dump the local TLPDB.
405 --remote
407 Dump the remote TLPDB.
408 --json
410 Instead of dumping the actual content, the database is dumped as
411 JSON. For the format of JSON output see
412 "tlpkg/doc/JSON-formats.txt", format definition "TLPDB".
413 Exactly one of "--local" and "--remote" must be given.
415 In either case, the first line of the output specifies the repository
417 location, in this format:
418 "location-url" "\t" location
420 where "location-url" is the literal field name, followed by a tab, and
422 location is the file or url to the repository.
423 Line endings may be either LF or CRLF depending on the current
425 platform.
426 generate
428 generate [option...] language
429 generate [option...] language.dat
430 generate [option...] language.def
431 generate [option...] language.dat.lua
432 The "generate" action overwrites any manual changes made in the
434 respective files: it recreates them from scratch based on the
435 information of the installed packages, plus local adaptions. The TeX
436 Live installer and "tlmgr" routinely call "generate" for all of these
437 files.
438 For managing your own fonts, please read the "updmap --help"
440 information and/or <https://tug.org/fonts/fontinstall.html>.
441 For managing your own formats, please read the "fmtutil --help"
443 information.
444 In more detail: "generate" remakes any of the configuration files
446 "language.dat", "language.def", and "language.dat.lua" from the
447 information present in the local TLPDB, plus locally-maintained files.
448 The locally-maintained files are "language-local.dat",
450 "language-local.def", or "language-local.dat.lua", searched for in
451 "TEXMFLOCAL" in the respective directories. If local additions are
452 present, the final file is made by starting with the main file,
453 omitting any entries that the local file specifies to be disabled, and
454 finally appending the local file.
455 (Historical note: The formerly supported "updmap-local.cfg" and
457 "fmtutil-local.cnf" are no longer read, since "updmap" and "fmtutil"
458 now reads and supports multiple configuration files. Thus, local
459 additions can and should be put into an "updmap.cfg" of "fmtutil.cnf"
460 file in "TEXMFLOCAL". The "generate updmap" and "generate fmtutil"
461 actions no longer exist.)
462 Local files specify entries to be disabled with a comment line, namely
464 one of these:
465 %!NAME
467 --!NAME
468 where "language.dat" and "language.def" use "%", and "language.dat.lua"
470 use "--". In all cases, the name is the respective format name or
471 hyphenation pattern identifier. Examples:
472 %!german
474 --!usenglishmax
475 (Of course, you're not likely to actually want to disable those
477 particular items. They're just examples.)
478 After such a disabling line, the local file can include another entry
480 for the same item, if a different definition is desired. In general,
481 except for the special disabling lines, the local files follow the same
482 syntax as the master files.
483 The form "generate language" recreates all three files "language.dat",
485 "language.def", and "language.dat.lua", while the forms with an
486 extension recreates only that given language file.
487 Options:
489 --dest output_file
491 specifies the output file (defaults to the respective location in
492 "TEXMFSYSVAR"). If "--dest" is given to "generate language", it
493 serves as a basename onto which ".dat" will be appended for the
494 name of the "language.dat" output file, ".def" will be appended to
495 the value for the name of the "language.def" output file, and
496 ".dat.lua" to the name of the "language.dat.lua" file. (This is
497 just to avoid overwriting; if you want a specific name for each
498 output file, we recommend invoking "tlmgr" twice.)
499 --localcfg local_conf_file
501 specifies the (optional) local additions (defaults to the
502 respective location in "TEXMFLOCAL").
503 --rebuild-sys
505 tells "tlmgr" to run necessary programs after config files have
506 been regenerated. These are: "fmtutil-sys --all" after "generate
507 fmtutil", "fmtutil-sys --byhyphen .../language.dat" after "generate
508 language.dat", and "fmtutil-sys --byhyphen .../language.def" after
509 "generate language.def".
510 These subsequent calls cause the newly-generated files to actually
512 take effect. This is not done by default since those calls are
513 lengthy processes and one might want to made several related
514 changes in succession before invoking these programs.
515 The respective locations are as follows:
517 tex/generic/config/language.dat (and language-local.dat)
519 tex/generic/config/language.def (and language-local.def)
520 tex/generic/config/language.dat.lua (and language-local.dat.lua)
521 gui
523 Start the graphical user interface. See GUI below.
524 info
526 info [option...] pkg...
527 info [option...] collections
528 info [option...] schemes
529 With no argument, lists all packages available at the package
530 repository, prefixing those already installed with "i".
531 With the single word "collections" or "schemes" as the argument,
533 lists the request type instead of all packages.
534 With any other arguments, display information about pkg: the name,
536 category, short and long description, sizes, installation status,
537 and TeX Live revision number. If pkg is not locally installed,
538 searches in the remote installation source.
539 For normal packages (not collections or schemes), the sizes of the
541 four groups of files (run/src/doc/bin files) are shown separately.
542 For collections, the cumulative size is shown, including all
543 directly-dependent packages (but not dependent collections). For
544 schemes, the cumulative size is also shown, including all directly-
545 dependent collections and packages.
546 If pkg is not found locally or remotely, the search action is used
548 and lists matching packages and files.
549 It also displays information taken from the TeX Catalogue, namely
551 the package version, date, and license. Consider these, especially
552 the package version, as approximations only, due to timing skew of
553 the updates of the different pieces. By contrast, the "revision"
554 value comes directly from TL and is reliable.
555 The former actions "show" and "list" are merged into this action,
557 but are still supported for backward compatibility.
558 Options:
560 --list
562 If the option "--list" is given with a package, the list of
563 contained files is also shown, including those for platform-
564 specific dependencies. When given with schemes and
565 collections, "--list" outputs their dependencies in a similar
566 way.
567 --only-installed
569 If this option is given, the installation source will not be
570 used; only locally installed packages, collections, or schemes
571 are listed.
572 --only-remote
574 Only list packages from the remote repository. Useful when
575 checking what is available in a remote repository using "tlmgr
576 --repo ... --only-remote info". Note that "--only-installed"
577 and "--only-remote" cannot both be specified.
578 --data "item1,item2,..."
580 If the option "--data" is given, its argument must be a comma
581 separated list of field names from: "name", "category",
582 "localrev", "remoterev", "shortdesc", "longdesc", "installed",
583 "size", "relocatable", "depends", "cat-version", "cat-date", or
584 "cat-license". In this case the requested packages' information
585 is listed in CSV format one package per line, and the column
586 information is given by the "itemN". The "depends" column
587 contains the name of all dependencies separated by ":".
588 --json
590 In case "--json" is specified, the output is a JSON encoded
591 array where each array element is the JSON representation of a
592 single "TLPOBJ" but with additional information. For details
593 see "tlpkg/doc/JSON-formats.txt", format definition:
594 "TLPOBJINFO". If both "--json" and "--data" are given,
595 "--json" takes precedence.
596 init-usertree
598 Sets up a texmf tree for so-called user mode management, either the
599 default user tree ("TEXMFHOME"), or one specified on the command line
600 with "--usertree". See "USER MODE" below.
601 install [option...] pkg...
603 Install each pkg given on the command line, if it is not already
604 installed. It does not touch existing packages; see the "update"
605 action for how to get the latest version of a package.
606 By default this also installs all packages on which the given pkgs are
608 dependent. Options:
609 --dry-run
611 Nothing is actually installed; instead, the actions to be performed
612 are written to the terminal.
613 --file
615 Instead of fetching a package from the installation repository, use
616 the package files given on the command line. These files must be
617 standard TeX Live package files (with contained tlpobj file).
618 --force
620 If updates to "tlmgr" itself (or other parts of the basic
621 infrastructure) are present, "tlmgr" will bail out and not perform
622 the installation unless this option is given. Not recommended.
623 --no-depends
625 Do not install dependencies. (By default, installing a package
626 ensures that all dependencies of this package are fulfilled.)
627 --no-depends-at-all
629 Normally, when you install a package which ships binary files the
630 respective binary package will also be installed. That is, for a
631 package "foo", the package "foo.i386-linux" will also be installed
632 on an "i386-linux" system. This option suppresses this behavior,
633 and also implies "--no-depends". Don't use it unless you are sure
634 of what you are doing.
635 --reinstall
637 Reinstall a package (including dependencies for collections) even
638 if it already seems to be installed (i.e, is present in the TLPDB).
639 This is useful to recover from accidental removal of files in the
640 hierarchy.
641 When re-installing, only dependencies on normal packages are
643 followed (i.e., not those of category Scheme or Collection).
644 --with-doc
646 --with-src
647 While not recommended, the "install-tl" program provides an option
648 to omit installation of all documentation and/or source files. (By
649 default, everything is installed.) After such an installation, you
650 may find that you want the documentation or source files for a
651 given package after all. You can get them by using these options
652 in conjunction with "--reinstall", as in (using the "fontspec"
653 package as the example):
654 tlmgr install --reinstall --with-doc --with-src fontspec
656 This action does not automatically add new symlinks in system
658 directories; you need to run "tlmgr path add" ("path") yourself if you
659 are using this feature and want new symlinks added.
660 key
662 key list
663 key add file
664 key remove keyid
665 The action "key" allows listing, adding and removing additional GPG
666 keys to the set of trusted keys, that is, those that are used to
667 verify the TeX Live databases.
668 With the "list" argument, "key" lists all keys.
670 The "add" argument requires another argument, either a filename or
672 "-" for stdin, from which the key is added. The key is added to the
673 local keyring "GNUPGHOME/repository-keys.gpg", which is normally
674 "tlpkg/gpg/repository-keys.gpg".
675 The "remove" argument requires a key id and removes the requested
677 id from the local keyring.
678 list
680 Synonym for "info".
681 option
683 option [--json] [show]
684 option [--json] showall|help
685 option key [value]
686 The first form, "show", shows the global TeX Live settings currently
688 saved in the TLPDB with a short description and the "key" used for
689 changing it in parentheses.
690 The second form, "showall", is similar, but also shows options which
692 can be defined but are not currently set to any value ("help" is a
693 synonym).
694 Both "show..." forms take an option "--json", which dumps the option
696 information in JSON format. In this case, both forms dump the same
697 data. For the format of the JSON output see
698 "tlpkg/doc/JSON-formats.txt", format definition "TLOPTION".
699 In the third form, with key, if value is not given, the setting for key
701 is displayed. If value is present, key is set to value.
702 Possible values for key are (run "tlmgr option showall" for the
704 definitive list):
705 repository (default package repository),
707 formats (generate formats at installation or update time),
708 postcode (run postinst code blobs)
709 docfiles (install documentation files),
710 srcfiles (install source files),
711 backupdir (default directory for backups),
712 autobackup (number of backups to keep).
713 sys_bin (directory to which executables are linked by the path action)
714 sys_man (directory to which man pages are linked by the path action)
715 sys_info (directory to which Info files are linked by the path action)
716 desktop_integration (Windows-only: create Start menu shortcuts)
717 fileassocs (Windows-only: change file associations)
718 multiuser (Windows-only: install for all users)
719 One common use of "option" is to permanently change the installation to
721 get further updates from the Internet, after originally installing from
722 DVD. To do this, you can run
723 tlmgr option repository http://mirror.ctan.org/systems/texlive/tlnet
725 The "install-tl" documentation has more information about the possible
727 values for "repository". (For backward compatibility, "location" can
728 be used as a synonym for "repository".)
729 If "formats" is set (this is the default), then formats are regenerated
731 when either the engine or the format files have changed. Disable this
732 only when you know how and want to regenerate formats yourself whenever
733 needed (which is often, in practice).
734 The "postcode" option controls execution of per-package
736 postinstallation action code. It is set by default, and again
737 disabling is not likely to be of interest except to developers doing
738 debugging.
739 The "docfiles" and "srcfiles" options control the installation of their
741 respective file groups (documentation, sources; grouping is
742 approximate) per package. By default both are enabled (1). Either or
743 both can be disabled (set to 0) if disk space is limited or for minimal
744 testing installations, etc. When disabled, the respective files are
745 not downloaded at all.
746 The options "autobackup" and "backupdir" determine the defaults for the
748 actions "update", "backup" and "restore". These three actions need a
749 directory in which to read or write the backups. If "--backupdir" is
750 not specified on the command line, the "backupdir" option value is used
751 (if set). The TL installer sets "backupdir" to ".../tlpkg/backups",
752 under the TL root installation directory.
753 The "autobackup" option (de)activates automatic generation of backups.
755 Its value is an integer. If the "autobackup" value is "-1", no backups
756 are removed. If "autobackup" is 0 or more, it specifies the number of
757 backups to keep. Thus, backups are disabled if the value is 0. In the
758 "--clean" mode of the "backup" action this option also specifies the
759 number to be kept. The default value is 1, so that backups are made,
760 but only one backup is kept.
761 To setup "autobackup" to "-1" on the command line, use:
763 tlmgr option -- autobackup -1
765 The "--" avoids having the "-1" treated as an option. (The "--" stops
767 parsing for options at the point where it appears; this is a general
768 feature across most Unix programs.)
769 The "sys_bin", "sys_man", and "sys_info" options are used on Unix
771 systems to control the generation of links for executables, Info files
772 and man pages. See the "path" action for details.
773 The last three options affect behavior on Windows installations. If
775 "desktop_integration" is set, then some packages will install items in
776 a sub-folder of the Start menu for "tlmgr gui", documentation, etc. If
777 "fileassocs" is set, Windows file associations are made (see also the
778 "postaction" action). Finally, if "multiuser" is set, then adaptions
779 to the registry and the menus are done for all users on the system
780 instead of only the current user. All three options are on by default.
781 paper
783 paper [a4|letter]
784 <[xdvi|pdftex|dvips|dvipdfmx|context|psutils] paper [papersize|--list]>
785 paper --json
786 With no arguments ("tlmgr paper"), shows the default paper size setting
788 for all known programs.
789 With one argument (e.g., "tlmgr paper a4"), sets the default for all
791 known programs to that paper size.
792 With a program given as the first argument and no paper size specified
794 (e.g., "tlmgr dvips paper"), shows the default paper size for that
795 program.
796 With a program given as the first argument and a paper size as the last
798 argument (e.g., "tlmgr dvips paper a4"), set the default for that
799 program to that paper size.
800 With a program given as the first argument and "--list" given as the
802 last argument (e.g., "tlmgr dvips paper --list"), shows all valid paper
803 sizes for that program. The first size shown is the default.
804 If "--json" is specified without other options, the paper setup is
806 dumped in JSON format. For the format of JSON output see
807 "tlpkg/doc/JSON-formats.txt", format definition "TLPAPER".
808 Incidentally, this syntax of having a specific program name before the
810 "paper" keyword is unusual. It is inherited from the longstanding
811 "texconfig" script, which supports other configuration settings for
812 some programs, notably "dvips". "tlmgr" does not support those extra
813 settings.
814 path
816 path [--w32mode=user|admin] add
817 path [--w32mode=user|admin] remove
818 On Unix, adds or removes symlinks for executables, man pages, and
819 info pages in the system directories specified by the respective
820 options (see the "option" description above). Does not change any
821 initialization files, either system or personal. Furthermore, any
822 executables added or removed by future updates are not taken care
823 of automatically; this command must be rerun as needed.
824 On Windows, the registry part where the binary directory is added
826 or removed is determined in the following way:
827 If the user has admin rights, and the option "--w32mode" is not
829 given, the setting w32_multi_user determines the location (i.e., if
830 it is on then the system path, otherwise the user path is changed).
831 If the user has admin rights, and the option "--w32mode" is given,
833 this option determines the path to be adjusted.
834 If the user does not have admin rights, and the option "--w32mode"
836 is not given, and the setting w32_multi_user is off, the user path
837 is changed, while if the setting w32_multi_user is on, a warning is
838 issued that the caller does not have enough privileges.
839 If the user does not have admin rights, and the option "--w32mode"
841 is given, it must be "user" and the user path will be adjusted. If
842 a user without admin rights uses the option "--w32mode admin" a
843 warning is issued that the caller does not have enough privileges.
844 pinning
846 The "pinning" action manages the pinning file, see "Pinning" below.
847 "pinning show"
849 Shows the current pinning data.
850 "pinning add" repo pkgglob...
852 Pins the packages matching the pkgglob(s) to the repository repo.
853 "pinning remove" repo pkgglob...
855 Any packages recorded in the pinning file matching the <pkgglob>s
856 for the given repository repo are removed.
857 "pinning remove repo --all"
859 Remove all pinning data for repository repo.
860 platform
862 platform list|add|remove platform...
863 platform set platform
864 platform set auto
865 "platform list" lists the TeX Live names of all the platforms
866 (a.k.a. architectures), ("i386-linux", ...) available at the
867 package repository.
868 "platform add" platform... adds the executables for each given
870 platform platform to the installation from the repository.
871 "platform remove" platform... removes the executables for each
873 given platform platform from the installation, but keeps the
874 currently running platform in any case.
875 "platform set" platform switches TeX Live to always use the given
877 platform instead of auto detection.
878 "platform set auto" switches TeX Live to auto detection mode for
880 platform.
881 Platform detection is needed to select the proper "xz" and "wget"
883 binaries that are shipped with TeX Live.
884 "arch" is a synonym for "platform".
886 Options:
888 --dry-run
890 Nothing is actually installed; instead, the actions to be
891 performed are written to the terminal.
892 postaction
894 postaction [option...] install [shortcut|fileassoc|script] [pkg...]
895 postaction [option...] remove [shortcut|fileassoc|script] [pkg...]
896 Carry out the postaction "shortcut", "fileassoc", or "script" given
897 as the second required argument in install or remove mode (which is
898 the first required argument), for either the packages given on the
899 command line, or for all if "--all" is given.
900 Options:
902 --w32mode=[user|admin]
904 If the option "--w32mode" is given the value "user", all
905 actions will only be carried out in the user-accessible parts
906 of the registry/filesystem, while the value "admin" selects the
907 system-wide parts of the registry for the file associations.
908 If you do not have enough permissions, using "--w32mode=admin"
909 will not succeed.
910 --fileassocmode=[1|2]
912 "--fileassocmode" specifies the action for file associations.
913 If it is set to 1 (the default), only new associations are
914 added; if it is set to 2, all associations are set to the TeX
915 Live programs. (See also "option fileassocs".)
916 --all
918 Carry out the postactions for all packages
919 print-platform
921 Print the TeX Live identifier for the detected platform
922 (hardware/operating system) combination to standard output, and exit.
923 "--print-arch" is a synonym.
924 print-platform-info
926 Print the TeX Live platform identifier, TL platform long name, and
927 original output from guess.
928 remove [option...] pkg...
930 Remove each pkg specified. Removing a collection removes all package
931 dependencies (unless "--no-depends" is specified), but not any
932 collection dependencies of that collection. However, when removing a
933 package, dependencies are never removed. Options:
934 --all
936 Uninstalls all of TeX Live, asking for confirmation unless
937 "--force" is also specified.
938 --backup
940 --backupdir directory
941 These options behave just as with the update action (q.v.), except
942 they apply to making backups of packages before they are removed.
943 The default is to make such a backup, that is, to save a copy of
944 packages before removal.
945 The "restore" action explains how to restore from a backup.
947 --no-depends
949 Do not remove dependent packages.
950 --no-depends-at-all
952 See above under install (and beware).
953 --force
955 By default, removal of a package or collection that is a dependency
956 of another collection or scheme is not allowed. With this option,
957 the package will be removed unconditionally. Use with care.
958 A package that has been removed using the "--force" option because
960 it is still listed in an installed collection or scheme will not be
961 updated, and will be mentioned as "forcibly removed" in the output
962 of "tlmgr update --list".
963 --dry-run
965 Nothing is actually removed; instead, the actions to be performed
966 are written to the terminal.
967 This action does not automatically remove symlinks to executables from
969 system directories; you need to run "tlmgr path remove" ("path")
970 yourself if you are using this feature and want stale symlinks removed.
971 repository
973 repository list
974 repository list path|url|tag
975 repository add path [tag]
976 repository remove path|tag
977 repository set path[#tag] [path[#tag] ...]
978 repository status
979 This action manages the list of repositories. See MULTIPLE
980 REPOSITORIES below for detailed explanations.
981 The first form, "repository list", lists all configured
983 repositories and the respective tags if set. If a path, url, or tag
984 is given after the "list" keyword, it is interpreted as the source
985 from which to initialize a TL database and lists the contained
986 packages. This can also be an otherwise-unused repository, either
987 local or remote. If the option "--with-platforms" is specified in
988 addition, for each package the available platforms (if any) are
989 also listed.
990 The form "repository add" adds a repository (optionally attaching a
992 tag) to the list of repositories, while "repository remove" removes
993 a repository, either by full path/url, or by tag.
994 The form "repository set" sets the list of available repositories
996 to the items given on the command line, overwriting previous
997 settings.
998 The form "repository status" reports the verification status of the
1000 loaded repositories with the format of one repository per line with
1001 fields separated by a single space:
1002 The tag (which can be the same as the url);
1004 = the url;
1005 = iff machine-readable output is specified, the verification
1007 code (a number);
1008 = a textual description of the verification status, as the last
1010 field extending to the end of line.
1011 That is, in normal (not machine-readable) output, the third field
1013 (numeric verification status) is not present.
1014 In all cases, one of the repositories must be tagged as "main";
1016 otherwise, all operations will fail!
1017 restore
1019 restore [option...] pkg [rev]
1020 restore [option...] --all
1021 Restore a package from a previously-made backup.
1022 If "--all" is given, try to restore the latest revision of all
1024 package backups found in the backup directory.
1025 Otherwise, if neither pkg nor rev are given, list the available
1027 backup revisions for all packages. With pkg given but no rev, list
1028 all available backup revisions of pkg.
1029 When listing available packages, "tlmgr" shows the revision, and in
1031 parenthesis the creation time if available (in format yyyy-mm-dd
1032 hh:mm).
1033 If (and only if) both pkg and a valid revision number rev are
1035 specified, try to restore the package from the specified backup.
1036 Options:
1038 --all
1040 Try to restore the latest revision of all package backups found
1041 in the backup directory. Additional non-option arguments (like
1042 pkg) are not allowed.
1043 --backupdir directory
1045 Specify the directory where the backups are to be found. If not
1046 given it will be taken from the configuration setting in the
1047 TLPDB.
1048 --dry-run
1050 Nothing is actually restored; instead, the actions to be
1051 performed are written to the terminal.
1052 --force
1054 Don't ask questions.
1055 --json
1057 When listing backups, the option "--json" turn on JSON output.
1058 The format is an array of JSON objects ("name", "rev", "date").
1059 For details see "tlpkg/doc/JSON-formats.txt", format
1060 definition: "TLBACKUPS". If both "--json" and "--data" are
1061 given, "--json" takes precedence.
1062 search
1064 search [option...] what
1065 search [option...] --file what
1066 search [option...] --all what
1067 By default, search the names, short descriptions, and long
1068 descriptions of all locally installed packages for the argument
1069 what, interpreted as a (Perl) regular expression.
1070 Options:
1072 --file
1074 List all filenames containing what.
1075 --all
1077 Search everything: package names, descriptions and filenames.
1078 --global
1080 Search the TeX Live Database of the installation medium,
1081 instead of the local installation.
1082 --word
1084 Restrict the search of package names and descriptions (but not
1085 filenames) to match only full words. For example, searching
1086 for "table" with this option will not output packages
1087 containing the word "tables" (unless they also contain the word
1088 "table" on its own).
1089 shell
1091 Starts an interactive mode, where tlmgr prompts for commands. This can
1092 be used directly, or for scripting. The first line of output is
1093 "protocol" n, where n is an unsigned number identifying the protocol
1094 version (currently 1).
1095 In general, tlmgr actions that can be given on the command line
1097 translate to commands in this shell mode. For example, you can say
1098 "update --list" to see what would be updated. The TLPDB is loaded the
1099 first time it is needed (not at the beginning), and used for the rest
1100 of the session.
1101 Besides these actions, a few commands are specific to shell mode:
1103 protocol
1105 Print "protocol n", the current protocol version.
1106 help
1108 Print pointers to this documentation.
1109 version
1111 Print tlmgr version information.
1112 quit, end, bye, byebye, EOF
1114 Exit.
1115 restart
1117 Restart "tlmgr shell" with the original command line; most useful
1118 when developing "tlmgr".
1119 load [local|remote]
1121 Explicitly load the local or remote, respectively, TLPDB.
1122 save
1124 Save the local TLPDB, presumably after other operations have
1125 changed it.
1126 get [var] =item set [var [val]]
1128 Get the value of var, or set it to val. Possible var names:
1129 "debug-translation", "machine-readable", "no-execute-actions",
1130 "require-verification", "verify-downloads", "repository", and
1131 "prompt". All except "repository" and "prompt" are booleans, taking
1132 values 0 and 1, and behave like the corresponding command line
1133 option. The "repository" variable takes a string, and sets the
1134 remote repository location. The "prompt" variable takes a string,
1135 and sets the current default prompt.
1136 If var or then val is not specified, it is prompted for.
1138 show
1140 Synonym for "info".
1141 uninstall
1143 Synonym for remove.
1144 update [option...] [pkg...]
1146 Updates the packages given as arguments to the latest version available
1147 at the installation source. Either "--all" or at least one pkg name
1148 must be specified. Options:
1149 --all
1151 Update all installed packages except for "tlmgr" itself. If updates
1152 to "tlmgr" itself are present, this gives an error, unless also the
1153 option "--force" or "--self" is given. (See below.)
1154 In addition to updating the installed packages, during the update
1156 of a collection the local installation is (by default) synchronized
1157 to the status of the collection on the server, for both additions
1158 and removals.
1159 This means that if a package has been removed on the server (and
1161 thus has also been removed from the respective collection), "tlmgr"
1162 will remove the package in the local installation. This is called
1163 ``auto-remove'' and is announced as such when using the option
1164 "--list". This auto-removal can be suppressed using the option
1165 "--no-auto-remove" (not recommended, see option description).
1166 Analogously, if a package has been added to a collection on the
1168 server that is also installed locally, it will be added to the
1169 local installation. This is called ``auto-install'' and is
1170 announced as such when using the option "--list". This auto-
1171 installation can be suppressed using the option "--no-auto-install"
1172 (also not recommended).
1173 An exception to the collection dependency checks (including the
1175 auto-installation of packages just mentioned) are those that have
1176 been ``forcibly removed'' by you, that is, you called "tlmgr remove
1177 --force" on them. (See the "remove" action documentation.) To
1178 reinstall any such forcibly removed packages use
1179 "--reinstall-forcibly-removed".
1180 To reiterate: automatic removals and additions are entirely
1182 determined by comparison of collections. Thus, if you manually
1183 install an individual package "foo" which is later removed from the
1184 server, "tlmgr" will not notice and will not remove it locally. (It
1185 has to be this way, without major rearchitecture work, because the
1186 tlpdb does not record the repository from which packages come
1187 from.)
1188 If you want to exclude some packages from the current update run
1190 (e.g., due to a slow link), see the "--exclude" option below.
1191 --self
1193 Update "tlmgr" itself (that is, the infrastructure packages) if
1194 updates to it are present. On Windows this includes updates to the
1195 private Perl interpreter shipped inside TeX Live.
1196 If this option is given together with either "--all" or a list of
1198 packages, then "tlmgr" will be updated first and, if this update
1199 succeeds, the new version will be restarted to complete the rest of
1200 the updates.
1201 In short:
1203 tlmgr update --self # update infrastructure only
1205 tlmgr update --self --all # update infrastructure and all packages
1206 tlmgr update --force --all # update all packages but *not* infrastructure
1207 # ... this last at your own risk, not recommended!
1208 --dry-run
1210 Nothing is actually installed; instead, the actions to be performed
1211 are written to the terminal. This is a more detailed report than
1212 "--list".
1213 --list [pkg]
1215 Concisely list the packages which would be updated, newly
1216 installed, or removed, without actually changing anything. If
1217 "--all" is also given, all available updates are listed. If
1218 "--self" is given, but not "--all", only updates to the critical
1219 packages (tlmgr, texlive infrastructure, perl on Windows, etc.)
1220 are listed. If neither "--all" nor "--self" is given, and in
1221 addition no pkg is given, then "--all" is assumed (thus, "tlmgr
1222 update --list" is the same as "tlmgr update --list --all"). If
1223 neither "--all" nor "--self" is given, but specific package names
1224 are given, those packages are checked for updates.
1225 --exclude pkg
1227 Exclude pkg from the update process. If this option is given more
1228 than once, its arguments accumulate.
1229 An argument pkg excludes both the package pkg itself and all its
1231 related platform-specific packages pkg.ARCH. For example,
1232 tlmgr update --all --exclude a2ping
1234 will not update "a2ping", "a2ping.i386-linux", or any other
1236 "a2ping."ARCH package.
1237 If this option specifies a package that would otherwise be a
1239 candidate for auto-installation, auto-removal, or reinstallation of
1240 a forcibly removed package, "tlmgr" quits with an error message.
1241 Excludes are not supported in these circumstances.
1242 This option can also be set permanently in the tlmgr config file
1244 with the key "update-exclude".
1245 --no-auto-remove [pkg...]
1247 By default, "tlmgr" tries to remove packages in an existing
1248 collection which have disappeared on the server, as described above
1249 under "--all". This option prevents such removals, either for all
1250 packages (with "--all"), or for just the given pkg names. This can
1251 lead to an inconsistent TeX installation, since packages are not
1252 infrequently renamed or replaced by their authors. Therefore this
1253 is not recommended.
1254 --no-auto-install [pkg...]
1256 Under normal circumstances "tlmgr" will install packages which are
1257 new on the server, as described above under "--all". This option
1258 prevents any such automatic installation, either for all packages
1259 (with "--all"), or the given pkg names.
1260 Furthermore, after the "tlmgr" run using this has finished, the
1262 packages that would have been auto-installed will be considered as
1263 forcibly removed. So, if "foobar" is the only new package on the
1264 server, then
1265 tlmgr update --all --no-auto-install
1267 is equivalent to
1269 tlmgr update --all
1271 tlmgr remove --force foobar
1272 Again, since packages are sometimes renamed or replaced, using this
1274 option is not recommended.
1275 --reinstall-forcibly-removed
1277 Under normal circumstances "tlmgr" will not install packages that
1278 have been forcibly removed by the user; that is, removed with
1279 "remove --force", or whose installation was prohibited by
1280 "--no-auto-install" during an earlier update.
1281 This option makes "tlmgr" ignore the forcible removals and re-
1283 install all such packages. This can be used to completely
1284 synchronize an installation with the server's idea of what is
1285 available:
1286 tlmgr update --reinstall-forcibly-removed --all
1288 --backup
1290 --backupdir directory
1291 These two options control the creation of backups of packages
1292 before updating; that is, backing up packages as currently
1293 installed. If neither option is given, no backup will made. If
1294 "--backupdir" is given and specifies a writable directory then a
1295 backup will be made in that location. If only "--backup" is given,
1296 then a backup will be made to the directory previously set via the
1297 "option" action (see below). If both are given then a backup will
1298 be made to the specified directory.
1299 You can also set options via the "option" action to automatically
1301 make backups for all packages, and/or keep only a certain number of
1302 backups.
1303 "tlmgr" always makes a temporary backup when updating packages, in
1305 case of download or other failure during an update. In contrast,
1306 the purpose of this "--backup" option is to save a persistent
1307 backup in case the actual content of the update causes problems,
1308 e.g., introduces an TeX incompatibility.
1309 The "restore" action explains how to restore from a backup.
1311 --no-depends
1313 If you call for updating a package normally all depending packages
1314 will also be checked for updates and updated if necessary. This
1315 switch suppresses this behavior.
1316 --no-depends-at-all
1318 See above under install (and beware).
1319 --force
1321 Force update of normal packages, without updating "tlmgr" itself
1322 (unless the "--self" option is also given). Not recommended.
1323 Also, "update --list" is still performed regardless of this option.
1325 If the package on the server is older than the package already
1327 installed (e.g., if the selected mirror is out of date), "tlmgr" does
1328 not downgrade. Also, packages for uninstalled platforms are not
1329 installed.
1330 "tlmgr" saves a copy of the "texlive.tlpdb" file used for an update
1332 with a suffix representing the repository url, as in
1333 "tlpkg/texlive.tlpdb."long-hash-string. These can be useful for
1334 fallback information, but if you don't like them accumulating (e.g.,
1335 "mirror.ctan.org" resolves to many different hosts, each resulting in a
1336 possibly different hash), it's harmless to delete them.
1337 This action does not automatically add or remove new symlinks in system
1339 directories; you need to run "tlmgr" "path" yourself if you are using
1340 this feature and want new symlinks added.
1341
1343 "tlmgr" reads two configuration files: one is system-wide, in
1344 "TEXMFSYSCONFIG/tlmgr/config", and the other is user-specific, in
1345 "TEXMFCONFIG/tlmgr/config". The user-specific one is the default for
1346 the "conf tlmgr" action. (Run "kpsewhich -var-value=TEXMFSYSCONFIG" or
1347 "... TEXMFCONFIG ..." to see the actual directory names.)
1348 A few defaults corresponding to command-line options can be set in
1350 these configuration files. In addition, the system-wide file can
1351 contain a directive to restrict the allowed actions.
1352 In these config files, empty lines and lines starting with # are
1354 ignored. All other lines must look like:
1355 key = value
1357 where the spaces are optional but the "=" is required.
1359 The allowed keys are:
1361 "auto-remove", value 0 or 1 (default 1), same as command-line option.
1363 "gui-expertmode", value 0 or 1 (default 1). This switches between the
1364 full GUI and a simplified GUI with only the most common settings.
1365 "gui-lang" llcode, with a language code value as with the command-line
1366 option.
1367 "no-checksums", value 0 or 1 (default 0, see below).
1368 "persistent-downloads", value 0 or 1 (default 1), same as command-line
1369 option.
1370 "require-verification", value 0 or 1 (default 0), same as command-line
1371 option.
1372 "update-exclude", value: comma-separated list of packages (no space
1373 allowed). Same as the command line option "--exclude" for the action
1374 "update".
1375 "verify-downloads", value 0 or 1 (default 1), same as command-line
1376 option.
1377 The system-wide config file can contain one additional key:
1379 "allowed-actions" action1 [,action,...] The value is a comma-separated
1381 list of "tlmgr" actions which are allowed to be executed when "tlmgr"
1382 is invoked in system mode (that is, without "--usermode").
1383 This allows distributors to include the "tlmgr" in their packaging,
1384 but allow only a restricted set of actions that do not interfere
1385 with their distro package manager. For native TeX Live
1386 installations, it doesn't make sense to set this.
1387 The "no-checksums" key needs more explanation. By default, package
1389 checksums computed and stored on the server (in the TLPDB) are compared
1390 to checksums computed locally after downloading. "no-checksums"
1391 disables this process.
1392 The checksum algorithm is SHA-512. Your system must have one of
1394 (looked for in this order) the Perl "Digest::SHA" module, the "openssl"
1395 program (<https://openssl.org>), the "sha512sum" program (from GNU
1396 Coreutils, <https://www.gnu.org/software/coreutils>), or finally the
1397 "shasum" program (just to support old Macs). If none of these are
1398 available, a warning is issued and "tlmgr" proceeds without checking
1399 checksums. (Incidentally, other SHA implementations, such as the pure
1400 Perl and pure Lua modules, are much too slow to be usable in our
1401 context.) "no-checksums" avoids the warning.
1402
1404 "tlmgr" and "install-tl" perform cryptographic verification if
1405 possible. If verification is performed and successful, the programs
1406 report "(verified)" after loading the TLPDB; otherwise, they report
1407 "(not verified)". But either way, by default the installation and/or
1408 updates proceed normally.
1409 If a program named "gpg" is available (that is, found in "PATH"), by
1411 default cryptographic signatures will be checked: we require the main
1412 repository be signed, but not any additional repositories. If "gpg" is
1413 not available, by default signatures are not checked and no
1414 verification is carried out, but "tlmgr" still proceeds normally.
1415 The behavior of the verification can be controlled by the command line
1417 and config file option "verify-repo" which takes one of the following
1418 values: "none", "main", or "all". With "none", no verification
1419 whatsoever is attempted. With "main" (the default) verification is
1420 required only for the main repository, and only if "gpg" is available;
1421 though attempted for all, missing signatures of subsidiary repositories
1422 will not result in an error. Finally, in the case of "all", "gpg" must
1423 be available and all repositories need to be signed.
1424 In all cases, if a signature is checked and fails to verify, an error
1426 is raised.
1427 Cryptographic verification requires checksum checking (described just
1429 above) to succeed, and a working GnuPG ("gpg") program (see below for
1430 search method). Then, unless cryptographic verification has been
1431 disabled, a signature file ("texlive.tlpdb.*.asc") of the checksum file
1432 is downloaded and the signature verified. The signature is created by
1433 the TeX Live Distribution GPG key 0x0D5E5D9106BAB6BC, which in turn is
1434 signed by Karl Berry's key 0x0716748A30D155AD and Norbert Preining's
1435 key 0x6CACA448860CDC13. All of these keys are obtainable from the
1436 standard key servers.
1437 Additional trusted keys can be added using the "key" action.
1439 Configuration of GnuPG invocation
1441 The executable used for GnuPG is searched as follows: If the
1442 environment variable "TL_GNUPG" is set, it is tested and used;
1443 otherwise "gpg" is checked; finally "gpg2" is checked.
1444 Further adaptation of the "gpg" invocation can be made using the two
1446 environment variables "TL_GNUPGHOME", which is passed to "gpg" as the
1447 value for "--homedir", and "TL_GNUPGARGS", which replaces the default
1448 options "--no-secmem-warning --no-permission-warning".
1449
1451 "tlmgr" provides a restricted way, called ``user mode'', to manage
1452 arbitrary texmf trees in the same way as the main installation. For
1453 example, this allows people without write permissions on the
1454 installation location to update/install packages into a tree of their
1455 own.
1456 "tlmgr" is switched into user mode with the command line option
1458 "--usermode". It does not switch automatically, nor is there any
1459 configuration file setting for it. Thus, this option has to be
1460 explicitly given every time user mode is to be activated.
1461 This mode of "tlmgr" works on a user tree, by default the value of the
1463 "TEXMFHOME" variable. This can be overridden with the command line
1464 option "--usertree". In the following when we speak of the user tree
1465 we mean either "TEXMFHOME" or the one given on the command line.
1466 Not all actions are allowed in user mode; "tlmgr" will warn you and not
1468 carry out any problematic actions. Currently not supported (and
1469 probably will never be) is the "platform" action. The "gui" action is
1470 currently not supported, but may be in a future release.
1471 Some "tlmgr" actions don't need any write permissions and thus work the
1473 same in user mode and normal mode. Currently these are: "check",
1474 "help", "list", "print-platform", "print-platform-info", "search",
1475 "show", "version".
1476 On the other hand, most of the actions dealing with package management
1478 do need write permissions, and thus behave differently in user mode, as
1479 described below: "install", "update", "remove", "option", "paper",
1480 "generate", "backup", "restore", "uninstall", "symlinks".
1481 Before using "tlmgr" in user mode, you have to set up the user tree
1483 with the "init-usertree" action. This creates usertree"/web2c" and
1484 usertree"/tlpkg/tlpobj", and a minimal usertree"/tlpkg/texlive.tlpdb".
1485 At that point, you can tell "tlmgr" to do the (supported) actions by
1486 adding the "--usermode" command line option.
1487 In user mode the file usertree"/tlpkg/texlive.tlpdb" contains only the
1489 packages that have been installed into the user tree using "tlmgr",
1490 plus additional options from the ``virtual'' package
1491 "00texlive.installation" (similar to the main installation's
1492 "texlive.tlpdb").
1493 All actions on packages in user mode can only be carried out on
1495 packages that are known as "relocatable". This excludes all packages
1496 containing executables and a few other core packages. Of the 2500 or
1497 so packages currently in TeX Live the vast majority are relocatable and
1498 can be installed into a user tree.
1499 Description of changes of actions in user mode:
1501 User mode install
1503 In user mode, the "install" action checks that the package and all
1504 dependencies are all either relocated or already installed in the
1505 system installation. If this is the case, it unpacks all containers to
1506 be installed into the user tree (to repeat, that's either "TEXMFHOME"
1507 or the value of "--usertree") and add the respective packages to the
1508 user tree's "texlive.tlpdb" (creating it if need be).
1509 Currently installing a collection in user mode installs all dependent
1511 packages, but in contrast to normal mode, does not install dependent
1512 collections. For example, in normal mode "tlmgr install
1513 collection-context" would install "collection-basic" and other
1514 collections, while in user mode, only the packages mentioned in
1515 "collection-context" are installed.
1516 If a package shipping map files is installed in user mode, a backup of
1518 the user's "updmap.cfg" in "USERTREE/web2c/" is made, and then this
1519 file regenerated from the list of installed packages.
1520 User mode backup, restore, remove, update
1522 In user mode, these actions check that all packages to be acted on are
1523 installed in the user tree before proceeding; otherwise, they behave
1524 just as in normal mode.
1525 User mode generate, option, paper
1527 In user mode, these actions operate only on the user tree's
1528 configuration files and/or "texlive.tlpdb". creates configuration
1529 files in user tree
1530
1532 The main TeX Live repository contains a vast array of packages.
1533 Nevertheless, additional local repositories can be useful to provide
1534 locally-installed resources, such as proprietary fonts and house
1535 styles. Also, alternative package repositories distribute packages
1536 that cannot or should not be included in TeX Live, for whatever reason.
1537 The simplest and most reliable method is to temporarily set the
1539 installation source to any repository (with the "-repository" or
1540 "option repository" command line options), and perform your operations.
1541 When you are using multiple repositories over a sustained length of
1543 time, however, explicitly switching between them becomes inconvenient.
1544 Thus, it's possible to tell "tlmgr" about additional repositories you
1545 want to use. The basic command is "tlmgr repository add". The rest of
1546 this section explains further.
1547 When using multiple repositories, one of them has to be set as the main
1549 repository, which distributes most of the installed packages. When you
1550 switch from a single repository installation to a multiple repository
1551 installation, the previous sole repository will be set as the main
1552 repository.
1553 By default, even if multiple repositories are configured, packages are
1555 still only installed from the main repository. Thus, simply adding a
1556 second repository does not actually enable installation of anything
1557 from there. You also have to specify which packages should be taken
1558 from the new repository, by specifying so-called ``pinning'' rules,
1559 described next.
1560 Pinning
1562 When a package "foo" is pinned to a repository, a package "foo" in any
1563 other repository, even if it has a higher revision number, will not be
1564 considered an installable candidate.
1565 As mentioned above, by default everything is pinned to the main
1567 repository. Let's now go through an example of setting up a second
1568 repository and enabling updates of a package from it.
1569 First, check that we have support for multiple repositories, and have
1571 only one enabled (as is the case by default):
1572 $ tlmgr repository list
1574 List of repositories (with tags if set):
1575 /var/www/norbert/tlnet
1576 Ok. Let's add the "tlcontrib" repository (this is a real repository
1578 hosted at <http://contrib.texlive.info>) with the tag "tlcontrib":
1579 $ tlmgr repository add http://contrib.texlive.info/current tlcontrib
1581 Check the repository list again:
1583 $ tlmgr repository list
1585 List of repositories (with tags if set):
1586 http://contrib.texlive.info/current (tlcontrib)
1587 /var/www/norbert/tlnet (main)
1588 Now we specify a pinning entry to get the package "classico" from
1590 "tlcontrib":
1591 $ tlmgr pinning add tlcontrib classico
1593 Check that we can find "classico":
1595 $ tlmgr show classico
1597 package: classico
1598 ...
1599 shortdesc: URW Classico fonts
1600 ...
1601 - install "classico":
1603 $ tlmgr install classico
1605 tlmgr: package repositories:
1606 ...
1607 [1/1, ??:??/??:??] install: classico @tlcontrib [737k]
1608 In the output here you can see that the "classico" package has been
1610 installed from the "tlcontrib" repository (@tlcontrib).
1611 Finally, "tlmgr pinning" also supports removing certain or all packages
1613 from a given repository:
1614 $ tlmgr pinning remove tlcontrib classico # remove just classico
1616 $ tlmgr pinning remove tlcontrib --all # take nothing from tlcontrib
1617 A summary of "tlmgr pinning" actions is given above.
1619
1621 The graphical user interface for "tlmgr" requires Perl/Tk
1622 <https://search.cpan.org/search?query=perl%2Ftk>. For Unix-based
1623 systems Perl/Tk (as well as Perl of course) has to be installed outside
1624 of TL. <https://tug.org/texlive/distro.html#perltk> has a list of
1625 invocations for some distros. For Windows the necessary modules are no
1626 longer shipped within TeX Live, so you'll have to have an external Perl
1627 available that includes them.
1628 We are talking here about the GUI built into tlmgr itself, not about
1630 the other tlmgr GUIs, which are: tlshell (Tcl/Tk-based), tlcockpit
1631 (Java-based) and, only on Macs, TeX Live Utility. These are invoked as
1632 separate programs.
1633 The GUI mode of tlmgr is started with the invocation "tlmgr gui";
1635 assuming Tk is loadable, the graphical user interface will be shown.
1636 The main window contains a menu bar, the main display, and a status
1637 area where messages normally shown on the console are displayed.
1638 Within the main display there are three main parts: the "Display
1640 configuration" area, the list of packages, and the action buttons.
1641 Also, at the top right the currently loaded repository is shown; this
1643 also acts as a button and when clicked will try to load the default
1644 repository. To load a different repository, see the "tlmgr" menu item.
1645 Finally, the status area at the bottom of the window gives additional
1647 information about what is going on.
1648 Main display
1650 Display configuration area
1651 The first part of the main display allows you to specify (filter) which
1653 packages are shown. By default, all are shown. Changes here are
1654 reflected right away.
1655 Status
1657 Select whether to show all packages (the default), only those
1658 installed, only those not installed, or only those with update
1659 available.
1660 Category
1662 Select which categories are shown: packages, collections, and/or
1663 schemes. These are briefly explained in the "DESCRIPTION" section
1664 above.
1665 Match
1667 Select packages matching for a specific pattern. By default, this
1668 searches both descriptions and filenames. You can also select a
1669 subset for searching.
1670 Selection
1672 Select packages to those selected, those not selected, or all.
1673 Here, ``selected'' means that the checkbox in the beginning of the
1674 line of a package is ticked.
1675 Display configuration buttons
1677 To the right there are three buttons: select all packages, select
1678 none (a.k.a. deselect all), and reset all these filters to the
1679 defaults, i.e., show all available.
1680 Package list area
1682 The second are of the main display lists all installed packages. If a
1684 repository is loaded, those that are available but not installed are
1685 also listed.
1686 Double clicking on a package line pops up an informational window with
1688 further details: the long description, included files, etc.
1689 Each line of the package list consists of the following items:
1691 a checkbox
1693 Used to select particular packages; some of the action buttons (see
1694 below) work only on the selected packages.
1695 package name
1697 The name (identifier) of the package as given in the database.
1698 local revision (and version)
1700 If the package is installed the TeX Live revision number for the
1701 installed package will be shown. If there is a catalogue version
1702 given in the database for this package, it will be shown in
1703 parentheses. However, the catalogue version, unlike the TL
1704 revision, is not guaranteed to reflect what is actually installed.
1705 remote revision (and version)
1707 If a repository has been loaded the revision of the package in the
1708 repository (if present) is shown. As with the local column, if a
1709 catalogue version is provided it will be displayed. And also as
1710 with the local column, the catalogue version may be stale.
1711 short description
1713 The short description of the package.
1714 Main display action buttons
1716 Below the list of packages are several buttons:
1718 Update all installed
1720 This calls "tlmgr update --all", i.e., tries to update all
1721 available packages. Below this button is a toggle to allow
1722 reinstallation of previously removed packages as part of this
1723 action.
1724 The other four buttons only work on the selected packages, i.e.,
1726 those where the checkbox at the beginning of the package line is
1727 ticked.
1728 Update
1730 Update only the selected packages.
1731 Install
1733 Install the selected packages; acts like "tlmgr install", i.e.,
1734 also installs dependencies. Thus, installing a collection installs
1735 all its constituent packages.
1736 Remove
1738 Removes the selected packages; acts like "tlmgr remove", i.e., it
1739 will also remove dependencies of collections (but not dependencies
1740 of normal packages).
1741 Backup
1743 Makes a backup of the selected packages; acts like "tlmgr backup".
1744 This action needs the option "backupdir" set (see "Options -"
1745 General>).
1746 Menu bar
1748 The following entries can be found in the menu bar:
1749 "tlmgr" menu
1751 The items here load various repositories: the default as specified
1752 in the TeX Live database, the default network repository, the
1753 repository specified on the command line (if any), and an
1754 arbitrarily manually-entered one. Also has the so-necessary "quit"
1755 operation.
1756 "Options menu"
1758 Provides access to several groups of options: "Paper"
1759 (configuration of default paper sizes), "Platforms" (only on Unix,
1760 configuration of the supported/installed platforms), "GUI Language"
1761 (select language used in the GUI interface), and "General"
1762 (everything else).
1763 Several toggles are also here. The first is "Expert options",
1765 which is set by default. If you turn this off, the next time you
1766 start the GUI a simplified screen will be shown that display only
1767 the most important functionality. This setting is saved in the
1768 configuration file of "tlmgr"; see "CONFIGURATION FILE FOR TLMGR"
1769 for details.
1770 The other toggles are all off by default: for debugging output, to
1772 disable the automatic installation of new packages, and to disable
1773 the automatic removal of packages deleted from the server. Playing
1774 with the choices of what is or isn't installed may lead to an
1775 inconsistent TeX Live installation; e.g., when a package is
1776 renamed.
1777 "Actions menu"
1779 Provides access to several actions: update the filename database
1780 (aka "ls-R", "mktexlsr", "texhash"), rebuild all formats
1781 ("fmtutil-sys --all"), update the font map database ("updmap-sys"),
1782 restore from a backup of a package, and use of symbolic links in
1783 system directories (not on Windows).
1784 The final action is to remove the entire TeX Live installation
1786 (also not on Windows).
1787 "Help menu"
1789 Provides access to the TeX Live manual (also on the web at
1790 <https://tug.org/texlive/doc.html>) and the usual ``About'' box.
1791 GUI options
1793 Some generic Perl/Tk options can be specified with "tlmgr gui" to
1794 control the display:
1795 "-background" color
1797 Set background color.
1798 "-font "" fontname fontsize """
1800 Set font, e.g., "tlmgr gui -font "helvetica 18"". The argument to
1801 "-font" must be quoted, i.e., passed as a single string.
1802 "-foreground" color
1804 Set foreground color.
1805 "-geometry" geomspec
1807 Set the X geometry, e.g., "tlmgr gui -geometry 1024x512-0+0"
1808 creates the window of (approximately) the given size in the upper-
1809 right corner of the display.
1810 "-xrm" xresource
1812 Pass the arbitrary X resource string xresource.
1813 A few other obscure options are recognized but not mentioned here. See
1815 the Perl/Tk documentation (<https://search.cpan.org/perldoc?Tk>) for
1816 the complete list, and any X documentation for general information.
1817
1819 With the "--machine-readable" option, "tlmgr" writes to stdout in the
1820 fixed line-oriented format described here, and the usual informational
1821 messages for human consumption are written to stderr (normally they are
1822 written to stdout). The idea is that a program can get all the
1823 information it needs by reading stdout.
1824 Currently this option only applies to the update, install, and "option"
1826 actions.
1827 Machine-readable "update" and "install" output
1829 The output format is as follows:
1830 fieldname "\t" value
1832 ...
1833 "end-of-header"
1834 pkgname status localrev serverrev size runtime esttot
1835 ...
1836 "end-of-updates"
1837 other output from post actions, not in machine readable form
1838 The header section currently has two fields: "location-url" (the
1840 repository source from which updates are being drawn), and
1841 "total-bytes" (the total number of bytes to be downloaded).
1842 The localrev and serverrev fields for each package are the revision
1844 numbers in the local installation and server repository, respectively.
1845 The size field is the number of bytes to be downloaded, i.e., the size
1846 of the compressed tar file for a network installation, not the unpacked
1847 size. The runtime and esttot fields are only present for updated and
1848 auto-install packages, and contain the currently passed time since
1849 start of installation/updates and the estimated total time.
1850 Line endings may be either LF or CRLF depending on the current
1852 platform.
1853 "location-url" location
1855 The location may be a url (including "file:///foo/bar/..."), or a
1856 directory name ("/foo/bar"). It is the package repository from
1857 which the new package information was drawn.
1858 "total-bytes" count
1860 The count is simply a decimal number, the sum of the sizes of all
1861 the packages that need updating or installing (which are listed
1862 subsequently).
1863 Then comes a line with only the literal string "end-of-header".
1865 Each following line until a line with literal string "end-of-updates"
1867 reports on one package. The fields on each line are separated by a
1868 tab. Here are the fields.
1869 pkgname
1871 The TeX Live package identifier, with a possible platform suffix
1872 for executables. For instance, "pdftex" and "pdftex.i386-linux"
1873 are given as two separate packages, one on each line.
1874 status
1876 The status of the package update. One character, as follows:
1877 "d" The package was removed on the server.
1879 "f" The package was removed in the local installation, even
1881 though a collection depended on it. (E.g., the user ran
1882 "tlmgr remove --force".)
1883 "u" Normal update is needed.
1885 "r" Reversed non-update: the locally-installed version is newer
1887 than the version on the server.
1888 "a" Automatically-determined need for installation, the package
1890 is new on the server and is (most probably) part of an
1891 installed collection.
1892 "i" Package will be installed and isn't present in the local
1894 installation (action install).
1895 "I" Package is already present but will be reinstalled (action
1897 install).
1898 localrev
1900 The revision number of the installed package, or "-" if it is not
1901 present locally.
1902 serverrev
1904 The revision number of the package on the server, or "-" if it is
1905 not present on the server.
1906 size
1908 The size in bytes of the package on the server. The sum of all the
1909 package sizes is given in the "total-bytes" header field mentioned
1910 above.
1911 runtime
1913 The run time since start of installations or updates.
1914 esttot
1916 The estimated total time.
1917 Machine-readable "option" output
1919 The output format is as follows:
1920 key "\t" value
1922 If a value is not saved in the database the string "(not set)" is
1924 shown.
1925 If you are developing a program that uses this output, and find that
1927 changes would be helpful, do not hesitate to write the mailing list.
1928
1930 "tlmgr" uses many of the standard TeX environment variables, as
1931 reported by, e.g., "tlmgr conf" ("conf").
1932 In addition, for ease in scripting and debugging, "tlmgr" looks for the
1934 following environment variables. These are not of interest for normal
1935 user installations.
1936 "TEXLIVE_COMPRESSOR"
1938 This variable allows selecting a different compressor program for
1939 backups and intermediate rollback containers. The order of
1940 selection is:
1941 1. If the environment variable "TEXLIVE_COMPRESSOR" is
1943 defined, use it; abort if it doesn't work. Possible values:
1944 "lz4", "gzip", "xz". The necessary options are added
1945 internally.
1946 2. If lz4 is available (either from the system or TL) and
1948 working, use that.
1949 3. If gzip is available (from the system) and working, use
1951 that.
1952 4. If xz is available (either from the system or TL) and
1954 working, use that.
1955 lz4 and gzip are faster in creating tlmgr's local backups, hence
1957 they are preferred. The unconditional use of xz for the tlnet
1958 containers is unaffected, to minimize download sizes.
1959 "TEXLIVE_DOWNLOADER"
1961 "TL_DOWNLOAD_PROGRAM"
1962 "TL_DOWNLOAD_ARGS"
1963 These options allow selecting different download programs then the
1964 ones automatically selected by the installer. The order of
1965 selection is:
1966 1. If the environment variable "TEXLIVE_DOWNLOADER" is
1968 defined, use it; abort if the specified program doesn't
1969 work. Possible values: "lwp", "curl", "wget". The necessary
1970 options are added internally.
1971 2. If the environment variable "TL_DOWNLOAD_PROGRAM" is
1973 defined (can be any value), use it together with
1974 "TL_DOWNLOAD_ARGS"; abort if it doesn't work.
1975 3. If LWP is available and working, use that (by far the most
1977 efficient method, as it supports persistent downloads).
1978 4. If curl is available (from the system) and working, use
1980 that.
1981 5. If wget is available (either from the system or TL) and
1983 working, use that.
1984 TL provides "wget" binaries for platforms where necessary, so some
1986 download method should always be available.
1987 "TEXLIVE_PREFER_OWN"
1989 By default, compression and download programs provided by the
1990 system, i.e., found along "PATH" are preferred over those shipped
1991 with TeX Live.
1992 This can create problems with systems that are too old, and so can
1994 be overridden by setting the environment variable
1995 "TEXLIVE_PREFER_OWN" to 1. In this case, executables shipped with
1996 TL will be preferred.
1997 Extra compression/download programs not provided by TL, such as
1999 gzip, lwp, and curl, are still checked for on the system and used
2000 if available, per the above. "TEXLIVE_PREFER_OWN" only applies when
2001 the program being checked for is shipped with TL, namely the lz4
2002 and xz compressors and wget downloader.
2003 Exception: on Windows, the "tar.exe" shipped with TL is always
2005 used, regardless of any setting.
2006
2008 This script and its documentation were written for the TeX Live
2009 distribution (<https://tug.org/texlive>) and both are licensed under
2010 the GNU General Public License Version 2 or later.
2011 $Id: tlmgr.pl 53803 2020-02-16 17:17:22Z karl $
2013perl v5.30.1 2020-02-16 TLMGR(1)