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 https://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 "https://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 --command-logfile file
175 "tlmgr" logs the output of all programs invoked (mktexlr, mtxrun,
176 fmtutil, updmap) to a separate log file, by default
177 "TEXMFSYSVAR/web2c/tlmgr-commands.log". This option allows you to
178 specify a different file for the log.
179 --debug-translation
181 In GUI mode, this switch tells "tlmgr" to report any untranslated
182 (or missing) messages to standard error. This can help translators
183 to see what remains to be done.
184 --machine-readable
186 Instead of the normal output intended for human consumption, write
187 (to standard output) a fixed format more suitable for machine
188 parsing. See the "MACHINE-READABLE OUTPUT" section below.
189 --no-execute-actions
191 Suppress the execution of the execute actions as defined in the
192 tlpsrc files. Documented only for completeness, as this is only
193 useful in debugging.
194 --package-logfile file
196 "tlmgr" logs all package actions (install, remove, update, failed
197 updates, failed restores) to a separate log file, by default
198 "TEXMFSYSVAR/web2c/tlmgr.log". This option allows you to specify a
199 different file for the log.
200 --pause
202 This option makes "tlmgr" wait for user input before exiting.
203 Useful on Windows to avoid disappearing command windows.
204 --persistent-downloads
206 --no-persistent-downloads
207 For network-based installations, this option (on by default) makes
208 "tlmgr" try to set up a persistent connection (using the "LWP" Perl
209 module). The idea is to open and reuse only one connection per
210 session between your computer and the server, instead of initiating
211 a new download for each package.
212 If this is not possible, "tlmgr" will fall back to using "wget".
214 To disable these persistent connections, use
215 "--no-persistent-downloads".
216 --pin-file
218 Change the pinning file location from
219 "TEXMFLOCAL/tlpkg/pinning.txt" (see "Pinning" below). Documented
220 only for completeness, as this is only useful in debugging.
221 --usermode
223 Activates user mode for this run of "tlmgr"; see "USER MODE" below.
224 --usertree dir
226 Uses dir for the tree in user mode; see "USER MODE" below.
227 --verify-repo=[none|main|all]
229 Defines the level of verification done: If "none" is specified, no
230 verification whatsoever is done. If "main" is given and a working
231 GnuPG ("gpg") binary is available, all repositories are checked,
232 but only the main repository is required to be signed. If "all" is
233 given, then all repositories need to be signed. See "CRYPTOGRAPHIC
234 VERIFICATION" below for details.
235 The standard options for TeX Live programs are also accepted:
237 "--help/-h/-?", "--version", "-q" (no informational messages), "-v"
238 (debugging messages, can be repeated). For the details about these,
239 see the "TeXLive::TLUtils" documentation.
240 The "--version" option shows version information about the TeX Live
242 release and about the "tlmgr" script itself. If "-v" is also given,
243 revision number for the loaded TeX Live Perl modules are shown, too.
244
246 help
247 Display this help information and exit (same as "--help", and on the
248 web at <https://tug.org/texlive/doc/tlmgr.html>). Sometimes the
249 "perldoc" and/or "PAGER" programs on the system have problems,
250 resulting in control characters being literally output. This can't
251 always be detected, but you can set the "NOPERLDOC" environment
252 variable and "perldoc" will not be used.
253 version
255 Gives version information (same as "--version").
256 If "-v" has been given the revisions of the used modules are reported,
258 too.
259 backup
261 backup [option...] --all
262 backup [option...] pkg...
263 If the "--clean" option is not specified, this action makes a
264 backup of the given packages, or all packages given "--all". These
265 backups are saved to the value of the "--backupdir" option, if that
266 is an existing and writable directory. If "--backupdir" is not
267 given, the "backupdir" option setting in the TLPDB is used, if
268 present. If both are missing, no backups are made. (The installer
269 sets "backupdir" to ".../tlpkg/backups", under the TL root
270 installation directory, so it is usually defined; see the "option"
271 description for more information.)
272 If the "--clean" option is specified, backups are pruned (removed)
274 instead of saved. The optional integer value N may be specified to
275 set the number of backups that will be retained when cleaning. If
276 "N" is not given, the value of the "autobackup" option is used. If
277 both are missing, an error is issued. For more details of backup
278 pruning, see the "option" action.
279 Options:
281 --backupdir directory
283 Overrides the "backupdir" option setting in the TLPDB. The
284 directory argument is required and must specify an existing,
285 writable directory where backups are to be placed.
286 --all
288 If "--clean" is not specified, make a backup of all packages in
289 the TeX Live installation; this will take quite a lot of space
290 and time. If "--clean" is specified, all packages are pruned.
291 --clean[=N]
293 Instead of making backups, prune the backup directory of old
294 backups, as explained above. The optional integer argument N
295 overrides the "autobackup" option set in the TLPDB. You must
296 use "--all" or a list of packages together with this option, as
297 desired.
298 --dry-run
300 Nothing is actually backed up or removed; instead, the actions
301 to be performed are written to the terminal.
302 candidates pkg
304 Shows the available candidate repositories for package pkg. See
305 "MULTIPLE REPOSITORIES" below.
306 check [option...] [depends|executes|files|runfiles|texmfdbs|all]
308 Execute one (or all) check(s) of the consistency of the installation.
309 If no problems are found, there will be no output. (To get a view of
310 what is being done, run "tlmgr -v check".)
311 depends
313 Lists those packages which occur as dependencies in an installed
314 collection, but are themselves not installed, and those packages
315 which are not contained in any collection.
316 If you call "tlmgr check collections" this test will be carried out
318 instead since former versions for "tlmgr" called it that way.
319 executes
321 Check that the files referred to by "execute" directives in the TeX
322 Live Database are present.
323 files
325 Checks that all files listed in the local TLPDB ("texlive.tlpdb")
326 are actually present, and lists those missing.
327 runfiles
329 List those filenames that are occurring more than one time in the
330 runfiles sections, except for known duplicates.
331 texmfdbs
333 Checks related to the "ls-R" files. If you have defined new trees,
334 or changed the "TEXMF" or "TEXMFDBS" variables, it can't hurt to
335 run this. It checks that:
336 - all items in "TEXMFDBS" have the "!!" prefix.
338 - all items in "TEXMFBDS" have an "ls-R" file (if they exist at
339 all).
340 - all items in "TEXMF" with "!!" are listed in "TEXMFDBS".
341 - all items in "TEXMF" with an "ls-R" file are listed in
342 "TEXMFDBS".
343 Options:
345 --use-svn
347 Use the output of "svn status" instead of listing the files; for
348 checking the TL development repository. (This is run nightly.)
349 conf
351 conf [texmf|tlmgr|updmap [--conffile file] [--delete] [key [value]]]
352 conf auxtrees [--conffile file] [show|add|remove] [value]
353 With only "conf", show general configuration information for TeX
354 Live, including active configuration files, path settings, and
355 more. This is like running "texconfig conf", but works on all
356 supported platforms.
357 With one of "conf texmf", "conf tlmgr", or "conf updmap", shows all
359 key/value pairs (i.e., all settings) as saved in "ROOT/texmf.cnf",
360 the user-specific "tlmgr" configuration file (see below), or the
361 first found (via "kpsewhich") "updmap.cfg" file, respectively.
362 If key is given in addition, shows the value of only that key in
364 the respective file. If option --delete is also given, the value
365 in the given configuration file is entirely removed (not just
366 commented out).
367 If value is given in addition, key is set to value in the
369 respective file. No error checking is done!
370 The "PATH" value shown by "conf" is as used by "tlmgr". The
372 directory in which the "tlmgr" executable is found is automatically
373 prepended to the PATH value inherited from the environment.
374 Here is a practical example of changing configuration values. If
376 the execution of (some or all) system commands via "\write18" was
377 left enabled during installation, you can disable it afterwards:
378 tlmgr conf texmf shell_escape 0
380 The subcommand "auxtrees" allows adding and removing arbitrary
382 additional texmf trees, completely under user control. "auxtrees
383 show" shows the list of additional trees, "auxtrees add" tree adds
384 a tree to the list, and "auxtrees remove" tree removes a tree from
385 the list (if present). The trees should not contain an "ls-R" file
386 (or files will not be found if the "ls-R" becomes stale). This
387 works by manipulating the Kpathsea variable "TEXMFAUXTREES", in (by
388 default) "ROOT/texmf.cnf". Example:
389 tlmgr conf auxtrees add /quick/test/tree
391 tlmgr conf auxtrees remove /quick/test/tree
392 In all cases the configuration file can be explicitly specified via
394 the option "--conffile" file, e.g., if you don't want to change the
395 system-wide configuration.
396 Warning: The general facility for changing configuration values is
398 here, but tinkering with settings in this way is strongly
399 discouraged. Again, no error checking on either keys or values is
400 done, so any sort of breakage is possible.
401 dump-tlpdb [option...] [--json]
403 Dump complete local or remote TLPDB to standard output, as-is. The
404 output is analogous to the "--machine-readable" output; see "MACHINE-
405 READABLE OUTPUT" section.
406 Options:
408 --local
410 Dump the local TLPDB.
411 --remote
413 Dump the remote TLPDB.
414 --json
416 Instead of dumping the actual content, the database is dumped as
417 JSON. For the format of JSON output see
418 "tlpkg/doc/JSON-formats.txt", format definition "TLPDB".
419 Exactly one of "--local" and "--remote" must be given.
421 In either case, the first line of the output specifies the repository
423 location, in this format:
424 "location-url" "\t" location
426 where "location-url" is the literal field name, followed by a tab, and
428 location is the file or url to the repository.
429 Line endings may be either LF or CRLF depending on the current
431 platform.
432 generate
434 generate [option...] language
435 generate [option...] language.dat
436 generate [option...] language.def
437 generate [option...] language.dat.lua
438 The "generate" action overwrites any manual changes made in the
440 respective files: it recreates them from scratch based on the
441 information of the installed packages, plus local adaptions. The TeX
442 Live installer and "tlmgr" routinely call "generate" for all of these
443 files.
444 For managing your own fonts, please read the "updmap --help"
446 information and/or <https://tug.org/fonts/fontinstall.html>.
447 For managing your own formats, please read the "fmtutil --help"
449 information.
450 In more detail: "generate" remakes any of the configuration files
452 "language.dat", "language.def", and "language.dat.lua" from the
453 information present in the local TLPDB, plus locally-maintained files.
454 The locally-maintained files are "language-local.dat",
456 "language-local.def", or "language-local.dat.lua", searched for in
457 "TEXMFLOCAL" in the respective directories. If local additions are
458 present, the final file is made by starting with the main file,
459 omitting any entries that the local file specifies to be disabled, and
460 finally appending the local file.
461 (Historical note: The formerly supported "updmap-local.cfg" and
463 "fmtutil-local.cnf" are no longer read, since "updmap" and "fmtutil"
464 now reads and supports multiple configuration files. Thus, local
465 additions can and should be put into an "updmap.cfg" of "fmtutil.cnf"
466 file in "TEXMFLOCAL". The "generate updmap" and "generate fmtutil"
467 actions no longer exist.)
468 Local files specify entries to be disabled with a comment line, namely
470 one of these:
471 %!NAME
473 --!NAME
474 where "language.dat" and "language.def" use "%", and "language.dat.lua"
476 use "--". In all cases, the name is the respective format name or
477 hyphenation pattern identifier. Examples:
478 %!german
480 --!usenglishmax
481 (Of course, you're not likely to actually want to disable those
483 particular items. They're just examples.)
484 After such a disabling line, the local file can include another entry
486 for the same item, if a different definition is desired. In general,
487 except for the special disabling lines, the local files follow the same
488 syntax as the master files.
489 The form "generate language" recreates all three files "language.dat",
491 "language.def", and "language.dat.lua", while the forms with an
492 extension recreates only that given language file.
493 Options:
495 --dest output_file
497 specifies the output file (defaults to the respective location in
498 "TEXMFSYSVAR"). If "--dest" is given to "generate language", it
499 serves as a basename onto which ".dat" will be appended for the
500 name of the "language.dat" output file, ".def" will be appended to
501 the value for the name of the "language.def" output file, and
502 ".dat.lua" to the name of the "language.dat.lua" file. (This is
503 just to avoid overwriting; if you want a specific name for each
504 output file, we recommend invoking "tlmgr" twice.)
505 --localcfg local_conf_file
507 specifies the (optional) local additions (defaults to the
508 respective location in "TEXMFLOCAL").
509 --rebuild-sys
511 tells "tlmgr" to run necessary programs after config files have
512 been regenerated. These are: "fmtutil-sys --all" after "generate
513 fmtutil", "fmtutil-sys --byhyphen .../language.dat" after "generate
514 language.dat", and "fmtutil-sys --byhyphen .../language.def" after
515 "generate language.def".
516 These subsequent calls cause the newly-generated files to actually
518 take effect. This is not done by default since those calls are
519 lengthy processes and one might want to made several related
520 changes in succession before invoking these programs.
521 The respective locations are as follows:
523 tex/generic/config/language.dat (and language-local.dat)
525 tex/generic/config/language.def (and language-local.def)
526 tex/generic/config/language.dat.lua (and language-local.dat.lua)
527 gui
529 Start the graphical user interface. See GUI below.
530 info
532 info [option...] pkg...
533 info [option...] collections
534 info [option...] schemes
535 With no argument, lists all packages available at the package
536 repository, prefixing those already installed with "i".
537 With the single word "collections" or "schemes" as the argument,
539 lists the request type instead of all packages.
540 With any other arguments, display information about pkg: the name,
542 category, short and long description, sizes, installation status,
543 and TeX Live revision number. If pkg is not locally installed,
544 searches in the remote installation source.
545 For normal packages (not collections or schemes), the sizes of the
547 four groups of files (run/src/doc/bin files) are shown separately.
548 For collections, the cumulative size is shown, including all
549 directly-dependent packages (but not dependent collections). For
550 schemes, the cumulative size is also shown, including all directly-
551 dependent collections and packages.
552 If pkg is not found locally or remotely, the search action is used
554 and lists matching packages and files.
555 It also displays information taken from the TeX Catalogue, namely
557 the package version, date, and license. Consider these, especially
558 the package version, as approximations only, due to timing skew of
559 the updates of the different pieces. By contrast, the "revision"
560 value comes directly from TL and is reliable.
561 The former actions "show" and "list" are merged into this action,
563 but are still supported for backward compatibility.
564 Options:
566 --list
568 If the option "--list" is given with a package, the list of
569 contained files is also shown, including those for platform-
570 specific dependencies. When given with schemes and
571 collections, "--list" outputs their dependencies in a similar
572 way.
573 --only-installed
575 If this option is given, the installation source will not be
576 used; only locally installed packages, collections, or schemes
577 are listed.
578 --only-remote
580 Only list packages from the remote repository. Useful when
581 checking what is available in a remote repository using "tlmgr
582 --repo ... --only-remote info". Note that "--only-installed"
583 and "--only-remote" cannot both be specified.
584 --data "item1,item2,..."
586 If the option "--data" is given, its argument must be a comma
587 or colon separated list of field names from: "name",
588 "category", "localrev", "remoterev", "shortdesc", "longdesc",
589 "installed", "size", "relocatable", "depends", "cat-version",
590 "cat-date", "cat-license", plus various "cat-contact-*" fields
591 (see below).
592 The "cat-*" fields all come from the TeX Catalogue
594 (<https://ctan.org/pkg/catalogue>). For each, there are two
595 more variants with prefix "l" and "r", e.g., "lcat-version" and
596 "rcat-version", which indicate the local and remote
597 information, respectively. The variants without "l" and "r"
598 show the most current one, which is normally the remote value.
599 The requested packages' information is listed in CSV format,
601 one package per line, and the column information is given by
602 the "itemN". The "depends" column contains the names of all the
603 dependencies separated by ":" characters.
604 At this writing, the "cat-contact-*" fields include: "home",
606 "repository", "support", "bugs", "announce", "development".
607 Each may be empty or a url value. A brief description is on the
608 CTAN upload page for new packages: <https://ctan.org/upload>.
609 --json
611 In case "--json" is specified, the output is a JSON encoded
612 array where each array element is the JSON representation of a
613 single "TLPOBJ" but with additional information. For details
614 see "tlpkg/doc/JSON-formats.txt", format definition:
615 "TLPOBJINFO". If both "--json" and "--data" are given, "--json"
616 takes precedence.
617 init-usertree
619 Sets up a texmf tree for so-called user mode management, either the
620 default user tree ("TEXMFHOME"), or one specified on the command line
621 with "--usertree". See "USER MODE" below.
622 install [option...] pkg...
624 Install each pkg given on the command line, if it is not already
625 installed. It does not touch existing packages; see the "update"
626 action for how to get the latest version of a package.
627 By default this also installs all packages on which the given pkgs are
629 dependent. Options:
630 --dry-run
632 Nothing is actually installed; instead, the actions to be performed
633 are written to the terminal.
634 --file
636 Instead of fetching a package from the installation repository, use
637 the package files given on the command line. These files must be
638 standard TeX Live package files (with contained tlpobj file).
639 --force
641 If updates to "tlmgr" itself (or other parts of the basic
642 infrastructure) are present, "tlmgr" will bail out and not perform
643 the installation unless this option is given. Not recommended.
644 --no-depends
646 Do not install dependencies. (By default, installing a package
647 ensures that all dependencies of this package are fulfilled.)
648 --no-depends-at-all
650 Normally, when you install a package which ships binary files the
651 respective binary package will also be installed. That is, for a
652 package "foo", the package "foo.i386-linux" will also be installed
653 on an "i386-linux" system. This option suppresses this behavior,
654 and also implies "--no-depends". Don't use it unless you are sure
655 of what you are doing.
656 --reinstall
658 Reinstall a package (including dependencies for collections) even
659 if it already seems to be installed (i.e, is present in the TLPDB).
660 This is useful to recover from accidental removal of files in the
661 hierarchy.
662 When re-installing, only dependencies on normal packages are
664 followed (i.e., not those of category Scheme or Collection).
665 --with-doc
667 --with-src
668 While not recommended, the "install-tl" program provides an option
669 to omit installation of all documentation and/or source files. (By
670 default, everything is installed.) After such an installation, you
671 may find that you want the documentation or source files for a
672 given package after all. You can get them by using these options
673 in conjunction with "--reinstall", as in (using the "fontspec"
674 package as the example):
675 tlmgr install --reinstall --with-doc --with-src fontspec
677 This action does not automatically add new symlinks in system
679 directories; you need to run "tlmgr path add" ("path") yourself if you
680 are using this feature and want new symlinks added.
681 key
683 key list
684 key add file
685 key remove keyid
686 The action "key" allows listing, adding and removing additional GPG
687 keys to the set of trusted keys, that is, those that are used to
688 verify the TeX Live databases.
689 With the "list" argument, "key" lists all keys.
691 The "add" argument requires another argument, either a filename or
693 "-" for stdin, from which the key is added. The key is added to the
694 local keyring "GNUPGHOME/repository-keys.gpg", which is normally
695 "tlpkg/gpg/repository-keys.gpg".
696 The "remove" argument requires a key id and removes the requested
698 id from the local keyring.
699 list
701 Synonym for "info".
702 option
704 option [--json] [show]
705 option [--json] showall|help
706 option key [value]
707 The first form, "show", shows the global TeX Live settings currently
709 saved in the TLPDB with a short description and the "key" used for
710 changing it in parentheses.
711 The second form, "showall", is similar, but also shows options which
713 can be defined but are not currently set to any value ("help" is a
714 synonym).
715 Both "show..." forms take an option "--json", which dumps the option
717 information in JSON format. In this case, both forms dump the same
718 data. For the format of the JSON output see
719 "tlpkg/doc/JSON-formats.txt", format definition "TLOPTION".
720 In the third form, with key, if value is not given, the setting for key
722 is displayed. If value is present, key is set to value.
723 Possible values for key are (run "tlmgr option showall" for the
725 definitive list):
726 repository (default package repository),
728 formats (generate formats at installation or update time),
729 postcode (run postinst code blobs)
730 docfiles (install documentation files),
731 srcfiles (install source files),
732 backupdir (default directory for backups),
733 autobackup (number of backups to keep).
734 sys_bin (directory to which executables are linked by the path action)
735 sys_man (directory to which man pages are linked by the path action)
736 sys_info (directory to which Info files are linked by the path action)
737 desktop_integration (Windows-only: create Start menu shortcuts)
738 fileassocs (Windows-only: change file associations)
739 multiuser (Windows-only: install for all users)
740 One common use of "option" is to permanently change the installation to
742 get further updates from the Internet, after originally installing from
743 DVD. To do this, you can run
744 tlmgr option repository https://mirror.ctan.org/systems/texlive/tlnet
746 The "install-tl" documentation has more information about the possible
748 values for "repository". (For backward compatibility, "location" can
749 be used as a synonym for "repository".)
750 If "formats" is set (this is the default), then formats are regenerated
752 when either the engine or the format files have changed. Disable this
753 only when you know how and want to regenerate formats yourself whenever
754 needed (which is often, in practice).
755 The "postcode" option controls execution of per-package
757 postinstallation action code. It is set by default, and again
758 disabling is not likely to be of interest except to developers doing
759 debugging.
760 The "docfiles" and "srcfiles" options control the installation of their
762 respective file groups (documentation, sources; grouping is
763 approximate) per package. By default both are enabled (1). Either or
764 both can be disabled (set to 0) if disk space is limited or for minimal
765 testing installations, etc. When disabled, the respective files are
766 not downloaded at all.
767 The options "autobackup" and "backupdir" determine the defaults for the
769 actions "update", "backup" and "restore". These three actions need a
770 directory in which to read or write the backups. If "--backupdir" is
771 not specified on the command line, the "backupdir" option value is used
772 (if set). The TL installer sets "backupdir" to ".../tlpkg/backups",
773 under the TL root installation directory.
774 The "autobackup" option (de)activates automatic generation of backups.
776 Its value is an integer. If the "autobackup" value is "-1", no backups
777 are removed. If "autobackup" is 0 or more, it specifies the number of
778 backups to keep. Thus, backups are disabled if the value is 0. In the
779 "--clean" mode of the "backup" action this option also specifies the
780 number to be kept. The default value is 1, so that backups are made,
781 but only one backup is kept.
782 To setup "autobackup" to "-1" on the command line, use:
784 tlmgr option -- autobackup -1
786 The "--" avoids having the "-1" treated as an option. (The "--" stops
788 parsing for options at the point where it appears; this is a general
789 feature across most Unix programs.)
790 The "sys_bin", "sys_man", and "sys_info" options are used on Unix
792 systems to control the generation of links for executables, Info files
793 and man pages. See the "path" action for details.
794 The last three options affect behavior on Windows installations. If
796 "desktop_integration" is set, then some packages will install items in
797 a sub-folder of the Start menu for "tlmgr gui", documentation, etc. If
798 "fileassocs" is set, Windows file associations are made (see also the
799 "postaction" action). Finally, if "multiuser" is set, then adaptions
800 to the registry and the menus are done for all users on the system
801 instead of only the current user. All three options are on by default.
802 paper
804 paper [a4|letter]
805 <[xdvi|pdftex|dvips|dvipdfmx|context|psutils] paper [papersize|--list]>
806 paper --json
807 With no arguments ("tlmgr paper"), shows the default paper size setting
809 for all known programs.
810 With one argument (e.g., "tlmgr paper a4"), sets the default for all
812 known programs to that paper size.
813 With a program given as the first argument and no paper size specified
815 (e.g., "tlmgr dvips paper"), shows the default paper size for that
816 program.
817 With a program given as the first argument and a paper size as the last
819 argument (e.g., "tlmgr dvips paper a4"), set the default for that
820 program to that paper size.
821 With a program given as the first argument and "--list" given as the
823 last argument (e.g., "tlmgr dvips paper --list"), shows all valid paper
824 sizes for that program. The first size shown is the default.
825 If "--json" is specified without other options, the paper setup is
827 dumped in JSON format. For the format of JSON output see
828 "tlpkg/doc/JSON-formats.txt", format definition "TLPAPER".
829 Incidentally, this syntax of having a specific program name before the
831 "paper" keyword is unusual. It is inherited from the longstanding
832 "texconfig" script, which supports other configuration settings for
833 some programs, notably "dvips". "tlmgr" does not support those extra
834 settings.
835 path
837 path [--windowsmode=user|admin] add
838 path [--windowsmode=user|admin] remove
839 On Unix, adds or removes symlinks for executables, man pages, and
840 info pages in the system directories specified by the respective
841 options (see the "option" description above). Does not change any
842 initialization files, either system or personal. Furthermore, any
843 executables added or removed by future updates are not taken care
844 of automatically; this command must be rerun as needed.
845 On Windows, the registry part where the binary directory is added
847 or removed is determined in the following way:
848 If the user has admin rights, and the option "--windowsmode" is not
850 given, the setting w32_multi_user determines the location (i.e., if
851 it is on then the system path, otherwise the user path is changed).
852 If the user has admin rights, and the option "--windowsmode" is
854 given, this option determines the path to be adjusted.
855 If the user does not have admin rights, and the option
857 "--windowsmode" is not given, and the setting w32_multi_user is
858 off, the user path is changed, while if the setting w32_multi_user
859 is on, a warning is issued that the caller does not have enough
860 privileges.
861 If the user does not have admin rights, and the option
863 "--windowsmode" is given, it must be "user" and the user path will
864 be adjusted. If a user without admin rights uses the option
865 "--windowsmode admin" a warning is issued that the caller does not
866 have enough privileges.
867 pinning
869 The "pinning" action manages the pinning file, see "Pinning" below.
870 "pinning show"
872 Shows the current pinning data.
873 "pinning add" repo pkgglob...
875 Pins the packages matching the pkgglob(s) to the repository repo.
876 "pinning remove" repo pkgglob...
878 Any packages recorded in the pinning file matching the <pkgglob>s
879 for the given repository repo are removed.
880 "pinning remove repo --all"
882 Remove all pinning data for repository repo.
883 platform
885 platform list|add|remove platform...
886 platform set platform
887 platform set auto
888 "platform list" lists the TeX Live names of all the platforms
889 (a.k.a. architectures), ("i386-linux", ...) available at the
890 package repository.
891 "platform add" platform... adds the executables for each given
893 platform platform to the installation from the repository.
894 "platform remove" platform... removes the executables for each
896 given platform platform from the installation, but keeps the
897 currently running platform in any case.
898 "platform set" platform switches TeX Live to always use the given
900 platform instead of auto detection.
901 "platform set auto" switches TeX Live to auto detection mode for
903 platform.
904 Platform detection is needed to select the proper "xz" and "wget"
906 binaries that are shipped with TeX Live.
907 "arch" is a synonym for "platform".
909 Options:
911 --dry-run
913 Nothing is actually installed; instead, the actions to be
914 performed are written to the terminal.
915 postaction
917 postaction [option...] install [shortcut|fileassoc|script] [pkg...]
918 postaction [option...] remove [shortcut|fileassoc|script] [pkg...]
919 Carry out the postaction "shortcut", "fileassoc", or "script" given
920 as the second required argument in install or remove mode (which is
921 the first required argument), for either the packages given on the
922 command line, or for all if "--all" is given.
923 Options:
925 --windowsmode=[user|admin]
927 If the option "--windowsmode" is given the value "user", all
928 actions will only be carried out in the user-accessible parts
929 of the registry/filesystem, while the value "admin" selects the
930 system-wide parts of the registry for the file associations.
931 If you do not have enough permissions, using
932 "--windowsmode=admin" will not succeed.
933 --fileassocmode=[1|2]
935 "--fileassocmode" specifies the action for file associations.
936 If it is set to 1 (the default), only new associations are
937 added; if it is set to 2, all associations are set to the TeX
938 Live programs. (See also "option fileassocs".)
939 --all
941 Carry out the postactions for all packages
942 print-platform
944 Print the TeX Live identifier for the detected platform
945 (hardware/operating system) combination to standard output, and exit.
946 "--print-arch" is a synonym.
947 print-platform-info
949 Print the TeX Live platform identifier, TL platform long name, and
950 original output from guess.
951 remove [option...] pkg...
953 Remove each pkg specified. Removing a collection removes all package
954 dependencies (unless "--no-depends" is specified), but not any
955 collection dependencies of that collection. However, when removing a
956 package, dependencies are never removed. Options:
957 --all
959 Uninstalls all of TeX Live, asking for confirmation unless
960 "--force" is also specified.
961 --backup
963 --backupdir directory
964 These options behave just as with the update action (q.v.), except
965 they apply to making backups of packages before they are removed.
966 The default is to make such a backup, that is, to save a copy of
967 packages before removal.
968 The "restore" action explains how to restore from a backup.
970 --no-depends
972 Do not remove dependent packages.
973 --no-depends-at-all
975 See above under install (and beware).
976 --force
978 By default, removal of a package or collection that is a dependency
979 of another collection or scheme is not allowed. With this option,
980 the package will be removed unconditionally. Use with care.
981 A package that has been removed using the "--force" option because
983 it is still listed in an installed collection or scheme will not be
984 updated, and will be mentioned as "forcibly removed" in the output
985 of "tlmgr update --list".
986 --dry-run
988 Nothing is actually removed; instead, the actions to be performed
989 are written to the terminal.
990 Except with "--all", this "remove" action does not automatically remove
992 symlinks to executables from system directories; you need to run "tlmgr
993 path remove" ("path") yourself if you remove an individual package with
994 a symlink in a system directory.
995 repository
997 repository list
998 repository list path|url|tag
999 repository add path [tag]
1000 repository remove path|tag
1001 repository set path[#tag] [path[#tag] ...]
1002 repository status
1003 This action manages the list of repositories. See MULTIPLE
1004 REPOSITORIES below for detailed explanations.
1005 The first form, "repository list", lists all configured
1007 repositories and the respective tags if set. If a path, url, or tag
1008 is given after the "list" keyword, it is interpreted as the source
1009 from which to initialize a TL database and lists the contained
1010 packages. This can also be an otherwise-unused repository, either
1011 local or remote. If the option "--with-platforms" is specified in
1012 addition, for each package the available platforms (if any) are
1013 also listed.
1014 The form "repository add" adds a repository (optionally attaching a
1016 tag) to the list of repositories, while "repository remove" removes
1017 a repository, either by full path/url, or by tag.
1018 The form "repository set" sets the list of available repositories
1020 to the items given on the command line, overwriting previous
1021 settings.
1022 The form "repository status" reports the verification status of the
1024 loaded repositories with the format of one repository per line with
1025 fields separated by a single space:
1026 The tag (which can be the same as the url);
1028 = the url;
1029 = iff machine-readable output is specified, the verification
1031 code (a number);
1032 = a textual description of the verification status, as the last
1034 field extending to the end of line.
1035 That is, in normal (not machine-readable) output, the third field
1037 (numeric verification status) is not present.
1038 In all cases, one of the repositories must be tagged as "main";
1040 otherwise, all operations will fail!
1041 restore
1043 restore [option...] pkg [rev]
1044 restore [option...] --all
1045 Restore a package from a previously-made backup.
1046 If "--all" is given, try to restore the latest revision of all
1048 package backups found in the backup directory.
1049 Otherwise, if neither pkg nor rev are given, list the available
1051 backup revisions for all packages. With pkg given but no rev, list
1052 all available backup revisions of pkg.
1053 When listing available packages, "tlmgr" shows the revision, and in
1055 parenthesis the creation time if available (in format yyyy-mm-dd
1056 hh:mm).
1057 If (and only if) both pkg and a valid revision number rev are
1059 specified, try to restore the package from the specified backup.
1060 Options:
1062 --all
1064 Try to restore the latest revision of all package backups found
1065 in the backup directory. Additional non-option arguments (like
1066 pkg) are not allowed.
1067 --backupdir directory
1069 Specify the directory where the backups are to be found. If not
1070 given it will be taken from the configuration setting in the
1071 TLPDB.
1072 --dry-run
1074 Nothing is actually restored; instead, the actions to be
1075 performed are written to the terminal.
1076 --force
1078 Don't ask questions.
1079 --json
1081 When listing backups, the option "--json" turn on JSON output.
1082 The format is an array of JSON objects ("name", "rev", "date").
1083 For details see "tlpkg/doc/JSON-formats.txt", format
1084 definition: "TLBACKUPS". If both "--json" and "--data" are
1085 given, "--json" takes precedence.
1086 search
1088 search [option...] what
1089 search [option...] --file what
1090 search [option...] --all what
1091 By default, search the names, short descriptions, and long
1092 descriptions of all locally installed packages for the argument
1093 what, interpreted as a (Perl) regular expression.
1094 Options:
1096 --file
1098 List all filenames containing what.
1099 --all
1101 Search everything: package names, descriptions and filenames.
1102 --global
1104 Search the TeX Live Database of the installation medium,
1105 instead of the local installation.
1106 --word
1108 Restrict the search of package names and descriptions (but not
1109 filenames) to match only full words. For example, searching
1110 for "table" with this option will not output packages
1111 containing the word "tables" (unless they also contain the word
1112 "table" on its own).
1113 shell
1115 Starts an interactive mode, where tlmgr prompts for commands. This can
1116 be used directly, or for scripting. The first line of output is
1117 "protocol" n, where n is an unsigned number identifying the protocol
1118 version (currently 1).
1119 In general, tlmgr actions that can be given on the command line
1121 translate to commands in this shell mode. For example, you can say
1122 "update --list" to see what would be updated. The TLPDB is loaded the
1123 first time it is needed (not at the beginning), and used for the rest
1124 of the session.
1125 Besides these actions, a few commands are specific to shell mode:
1127 protocol
1129 Print "protocol n", the current protocol version.
1130 help
1132 Print pointers to this documentation.
1133 version
1135 Print tlmgr version information.
1136 quit, end, bye, byebye, EOF
1138 Exit.
1139 restart
1141 Restart "tlmgr shell" with the original command line; most useful
1142 when developing "tlmgr".
1143 load [local|remote]
1145 Explicitly load the local or remote, respectively, TLPDB.
1146 save
1148 Save the local TLPDB, presumably after other operations have
1149 changed it.
1150 get [var] =item set [var [val]]
1152 Get the value of var, or set it to val. Possible var names:
1153 "debug-translation", "machine-readable", "no-execute-actions",
1154 "require-verification", "verify-downloads", "repository", and
1155 "prompt". All except "repository" and "prompt" are booleans, taking
1156 values 0 and 1, and behave like the corresponding command line
1157 option. The "repository" variable takes a string, and sets the
1158 remote repository location. The "prompt" variable takes a string,
1159 and sets the current default prompt.
1160 If var or then val is not specified, it is prompted for.
1162 show
1164 Synonym for "info".
1165 uninstall
1167 Synonym for remove.
1168 update [option...] [pkg...]
1170 Updates the packages given as arguments to the latest version available
1171 at the installation source. Either "--all" or at least one pkg name
1172 must be specified. Options:
1173 --all
1175 Update all installed packages except for "tlmgr" itself. If updates
1176 to "tlmgr" itself are present, this gives an error, unless also the
1177 option "--force" or "--self" is given. (See below.)
1178 In addition to updating the installed packages, during the update
1180 of a collection the local installation is (by default) synchronized
1181 to the status of the collection on the server, for both additions
1182 and removals.
1183 This means that if a package has been removed on the server (and
1185 thus has also been removed from the respective collection), "tlmgr"
1186 will remove the package in the local installation. This is called
1187 ``auto-remove'' and is announced as such when using the option
1188 "--list". This auto-removal can be suppressed using the option
1189 "--no-auto-remove" (not recommended, see option description).
1190 Analogously, if a package has been added to a collection on the
1192 server that is also installed locally, it will be added to the
1193 local installation. This is called ``auto-install'' and is
1194 announced as such when using the option "--list". This auto-
1195 installation can be suppressed using the option "--no-auto-install"
1196 (also not recommended).
1197 An exception to the collection dependency checks (including the
1199 auto-installation of packages just mentioned) are those that have
1200 been ``forcibly removed'' by you, that is, you called "tlmgr remove
1201 --force" on them. (See the "remove" action documentation.) To
1202 reinstall any such forcibly removed packages use
1203 "--reinstall-forcibly-removed".
1204 To reiterate: automatic removals and additions are entirely
1206 determined by comparison of collections. Thus, if you manually
1207 install an individual package "foo" which is later removed from the
1208 server, "tlmgr" will not notice and will not remove it locally. (It
1209 has to be this way, without major rearchitecture work, because the
1210 tlpdb does not record the repository from which packages come
1211 from.)
1212 If you want to exclude some packages from the current update run
1214 (e.g., due to a slow link), see the "--exclude" option below.
1215 --self
1217 Update "tlmgr" itself (that is, the infrastructure packages) if
1218 updates to it are present. On Windows this includes updates to the
1219 private Perl interpreter shipped inside TeX Live.
1220 If this option is given together with either "--all" or a list of
1222 packages, then "tlmgr" will be updated first and, if this update
1223 succeeds, the new version will be restarted to complete the rest of
1224 the updates.
1225 In short:
1227 tlmgr update --self # update infrastructure only
1229 tlmgr update --self --all # update infrastructure and all packages
1230 tlmgr update --force --all # update all packages but *not* infrastructure
1231 # ... this last at your own risk, not recommended!
1232 --dry-run
1234 Nothing is actually installed; instead, the actions to be performed
1235 are written to the terminal. This is a more detailed report than
1236 "--list".
1237 --list [pkg]
1239 Concisely list the packages which would be updated, newly
1240 installed, or removed, without actually changing anything. If
1241 "--all" is also given, all available updates are listed. If
1242 "--self" is given, but not "--all", only updates to the critical
1243 packages (tlmgr, texlive infrastructure, perl on Windows, etc.)
1244 are listed. If neither "--all" nor "--self" is given, and in
1245 addition no pkg is given, then "--all" is assumed (thus, "tlmgr
1246 update --list" is the same as "tlmgr update --list --all"). If
1247 neither "--all" nor "--self" is given, but specific package names
1248 are given, those packages are checked for updates.
1249 --exclude pkg
1251 Exclude pkg from the update process. If this option is given more
1252 than once, its arguments accumulate.
1253 An argument pkg excludes both the package pkg itself and all its
1255 related platform-specific packages pkg.ARCH. For example,
1256 tlmgr update --all --exclude a2ping
1258 will not update "a2ping", "a2ping.i386-linux", or any other
1260 "a2ping."ARCH package.
1261 If this option specifies a package that would otherwise be a
1263 candidate for auto-installation, auto-removal, or reinstallation of
1264 a forcibly removed package, "tlmgr" quits with an error message.
1265 Excludes are not supported in these circumstances.
1266 This option can also be set permanently in the tlmgr config file
1268 with the key "update-exclude".
1269 --no-auto-remove [pkg...]
1271 By default, "tlmgr" tries to remove packages in an existing
1272 collection which have disappeared on the server, as described above
1273 under "--all". This option prevents such removals, either for all
1274 packages (with "--all"), or for just the given pkg names. This can
1275 lead to an inconsistent TeX installation, since packages are not
1276 infrequently renamed or replaced by their authors. Therefore this
1277 is not recommended.
1278 --no-auto-install [pkg...]
1280 Under normal circumstances "tlmgr" will install packages which are
1281 new on the server, as described above under "--all". This option
1282 prevents any such automatic installation, either for all packages
1283 (with "--all"), or the given pkg names.
1284 Furthermore, after the "tlmgr" run using this has finished, the
1286 packages that would have been auto-installed will be considered as
1287 forcibly removed. So, if "foobar" is the only new package on the
1288 server, then
1289 tlmgr update --all --no-auto-install
1291 is equivalent to
1293 tlmgr update --all
1295 tlmgr remove --force foobar
1296 Again, since packages are sometimes renamed or replaced, using this
1298 option is not recommended.
1299 --reinstall-forcibly-removed
1301 Under normal circumstances "tlmgr" will not install packages that
1302 have been forcibly removed by the user; that is, removed with
1303 "remove --force", or whose installation was prohibited by
1304 "--no-auto-install" during an earlier update.
1305 This option makes "tlmgr" ignore the forcible removals and re-
1307 install all such packages. This can be used to completely
1308 synchronize an installation with the server's idea of what is
1309 available:
1310 tlmgr update --reinstall-forcibly-removed --all
1312 --backup
1314 --backupdir directory
1315 These two options control the creation of backups of packages
1316 before updating; that is, backing up packages as currently
1317 installed. If neither option is given, no backup will made. If
1318 "--backupdir" is given and specifies a writable directory then a
1319 backup will be made in that location. If only "--backup" is given,
1320 then a backup will be made to the directory previously set via the
1321 "option" action (see below). If both are given then a backup will
1322 be made to the specified directory.
1323 You can also set options via the "option" action to automatically
1325 make backups for all packages, and/or keep only a certain number of
1326 backups.
1327 "tlmgr" always makes a temporary backup when updating packages, in
1329 case of download or other failure during an update. In contrast,
1330 the purpose of this "--backup" option is to save a persistent
1331 backup in case the actual content of the update causes problems,
1332 e.g., introduces an TeX incompatibility.
1333 The "restore" action explains how to restore from a backup.
1335 --no-depends
1337 If you call for updating a package normally all depending packages
1338 will also be checked for updates and updated if necessary. This
1339 switch suppresses this behavior.
1340 --no-depends-at-all
1342 See above under install (and beware).
1343 --force
1345 Force update of normal packages, without updating "tlmgr" itself
1346 (unless the "--self" option is also given). Not recommended.
1347 Also, "update --list" is still performed regardless of this option.
1349 If the package on the server is older than the package already
1351 installed (e.g., if the selected mirror is out of date), "tlmgr" does
1352 not downgrade. Also, packages for uninstalled platforms are not
1353 installed.
1354 "tlmgr" saves one copy of the main "texlive.tlpdb" file used for an
1356 update with a suffix representing the repository url, as in
1357 "tlpkg/texlive.tlpdb.main."long-hash-string. Thus, even when many
1358 mirrors are used, only one main "tlpdb" backup is kept. For non-main
1359 repositories, which do not generally have (m)any mirrors, no pruning of
1360 backups is done.
1361 This action does not automatically add or remove new symlinks in system
1363 directories; you need to run "tlmgr" "path" yourself if you are using
1364 this feature and want new symlinks added.
1365
1367 "tlmgr" reads two configuration files: one is system-wide, in
1368 "TEXMFSYSCONFIG/tlmgr/config", and the other is user-specific, in
1369 "TEXMFCONFIG/tlmgr/config". The user-specific one is the default for
1370 the "conf tlmgr" action. (Run "kpsewhich -var-value=TEXMFSYSCONFIG" or
1371 "... TEXMFCONFIG ..." to see the actual directory names.)
1372 A few defaults corresponding to command-line options can be set in
1374 these configuration files. In addition, the system-wide file can
1375 contain a directive to restrict the allowed actions.
1376 In these config files, empty lines and lines starting with # are
1378 ignored. All other lines must look like:
1379 key = value
1381 where the spaces are optional but the "=" is required.
1383 The allowed keys are:
1385 "auto-remove =" 0 or 1 (default 1), same as command-line option.
1387 "gui-expertmode =" 0 or 1 (default 1). This switches between the full
1388 GUI and a simplified GUI with only the most common settings.
1389 "gui-lang =" llcode, with a language code value as with the command-
1390 line option.
1391 "no-checksums =" 0 or 1 (default 0, see below).
1392 "persistent-downloads =" 0 or 1 (default 1), same as command-line
1393 option.
1394 "require-verification =" 0 or 1 (default 0), same as command-line
1395 option.
1396 "tkfontscale =" floating-point number (default 1.0); scaling factor for
1397 fonts in the Tk-based frontends.
1398 "update-exclude =" comma-separated list of packages (no spaces
1399 allowed). Same as the command line option "--exclude" for the "update"
1400 action.
1401 "verify-downloads =" 0 or 1 (default 1), same as command-line option.
1402 The system-wide config file can contain one additional key:
1404 "allowed-actions =" action1[,action2,...] The value is a comma-
1406 separated list (no spaces) of "tlmgr" actions which are allowed to be
1407 executed when "tlmgr" is invoked in system mode (that is, without
1408 "--usermode"). This allows distributors to include "tlmgr" in their
1409 packaging, but allow only a restricted set of actions that do not
1410 interfere with their distro package manager. For native TeX Live
1411 installations, it doesn't make sense to set this.
1412 Finally, the "no-checksums" key needs more explanation. By default,
1414 package checksums computed and stored on the server (in the TLPDB) are
1415 compared to checksums computed locally after downloading.
1416 "no-checksums" disables this process. The checksum algorithm is
1417 SHA-512. Your system must have one of (looked for in this order) the
1418 Perl "Digest::SHA" module, the "openssl" program
1419 (<https://openssl.org>), the "sha512sum" program (from GNU Coreutils,
1420 <https://www.gnu.org/software/coreutils>), or finally the "shasum"
1421 program (just to support old Macs). If none of these are available, a
1422 warning is issued and "tlmgr" proceeds without checking checksums.
1423 "no-checksums" avoids the warning. (Incidentally, other SHA
1424 implementations, such as the pure Perl and pure Lua modules, are much
1425 too slow to be usable in our context.)
1426
1428 "tlmgr" and "install-tl" perform cryptographic verification if
1429 possible. If verification is performed and successful, the programs
1430 report "(verified)" after loading the TLPDB; otherwise, they report
1431 "(not verified)". But either way, by default the installation and/or
1432 updates proceed normally.
1433 If a program named "gpg" is available (that is, found in "PATH"), by
1435 default cryptographic signatures will be checked: we require the main
1436 repository be signed, but not any additional repositories. If "gpg" is
1437 not available, by default signatures are not checked and no
1438 verification is carried out, but "tlmgr" still proceeds normally.
1439 The behavior of the verification can be controlled by the command line
1441 and config file option "verify-repo" which takes one of the following
1442 values: "none", "main", or "all". With "none", no verification
1443 whatsoever is attempted. With "main" (the default) verification is
1444 required only for the main repository, and only if "gpg" is available;
1445 though attempted for all, missing signatures of subsidiary repositories
1446 will not result in an error. Finally, in the case of "all", "gpg" must
1447 be available and all repositories need to be signed.
1448 In all cases, if a signature is checked and fails to verify, an error
1450 is raised.
1451 Cryptographic verification requires checksum checking (described just
1453 above) to succeed, and a working GnuPG ("gpg") program (see below for
1454 search method). Then, unless cryptographic verification has been
1455 disabled, a signature file ("texlive.tlpdb.*.asc") of the checksum file
1456 is downloaded and the signature verified. The signature is created by
1457 the TeX Live Distribution GPG key 0x0D5E5D9106BAB6BC, which in turn is
1458 signed by Karl Berry's key 0x0716748A30D155AD and Norbert Preining's
1459 key 0x6CACA448860CDC13. All of these keys are obtainable from the
1460 standard key servers.
1461 Additional trusted keys can be added using the "key" action.
1463 Configuration of GnuPG invocation
1465 The executable used for GnuPG is searched as follows: If the
1466 environment variable "TL_GNUPG" is set, it is tested and used;
1467 otherwise "gpg" is checked; finally "gpg2" is checked.
1468 Further adaptation of the "gpg" invocation can be made using the two
1470 environment variables "TL_GNUPGHOME", which is passed to "gpg" as the
1471 value for "--homedir", and "TL_GNUPGARGS", which replaces the default
1472 options "--no-secmem-warning --no-permission-warning".
1473
1475 "tlmgr" provides a restricted way, called ``user mode'', to manage
1476 arbitrary texmf trees in the same way as the main installation. For
1477 example, this allows people without write permissions on the
1478 installation location to update/install packages into a tree of their
1479 own.
1480 "tlmgr" is switched into user mode with the command line option
1482 "--usermode". It does not switch automatically, nor is there any
1483 configuration file setting for it. Thus, this option has to be
1484 explicitly given every time user mode is to be activated.
1485 This mode of "tlmgr" works on a user tree, by default the value of the
1487 "TEXMFHOME" variable. This can be overridden with the command line
1488 option "--usertree". In the following when we speak of the user tree
1489 we mean either "TEXMFHOME" or the one given on the command line.
1490 Not all actions are allowed in user mode; "tlmgr" will warn you and not
1492 carry out any problematic actions. Currently not supported (and
1493 probably will never be) is the "platform" action. The "gui" action is
1494 currently not supported, but may be in a future release.
1495 Some "tlmgr" actions don't need any write permissions and thus work the
1497 same in user mode and normal mode. Currently these are: "check",
1498 "help", "list", "print-platform", "print-platform-info", "search",
1499 "show", "version".
1500 On the other hand, most of the actions dealing with package management
1502 do need write permissions, and thus behave differently in user mode, as
1503 described below: "install", "update", "remove", "option", "paper",
1504 "generate", "backup", "restore", "uninstall", "symlinks".
1505 Before using "tlmgr" in user mode, you have to set up the user tree
1507 with the "init-usertree" action. This creates usertree"/web2c" and
1508 usertree"/tlpkg/tlpobj", and a minimal usertree"/tlpkg/texlive.tlpdb".
1509 At that point, you can tell "tlmgr" to do the (supported) actions by
1510 adding the "--usermode" command line option.
1511 In user mode the file usertree"/tlpkg/texlive.tlpdb" contains only the
1513 packages that have been installed into the user tree using "tlmgr",
1514 plus additional options from the ``virtual'' package
1515 "00texlive.installation" (similar to the main installation's
1516 "texlive.tlpdb").
1517 All actions on packages in user mode can only be carried out on
1519 packages that are known as "relocatable". This excludes all packages
1520 containing executables and a few other core packages. Of the 2500 or
1521 so packages currently in TeX Live the vast majority are relocatable and
1522 can be installed into a user tree.
1523 Description of changes of actions in user mode:
1525 User mode install
1527 In user mode, the "install" action checks that the package and all
1528 dependencies are all either relocated or already installed in the
1529 system installation. If this is the case, it unpacks all containers to
1530 be installed into the user tree (to repeat, that's either "TEXMFHOME"
1531 or the value of "--usertree") and add the respective packages to the
1532 user tree's "texlive.tlpdb" (creating it if need be).
1533 Currently installing a collection in user mode installs all dependent
1535 packages, but in contrast to normal mode, does not install dependent
1536 collections. For example, in normal mode "tlmgr install
1537 collection-context" would install "collection-basic" and other
1538 collections, while in user mode, only the packages mentioned in
1539 "collection-context" are installed.
1540 If a package shipping map files is installed in user mode, a backup of
1542 the user's "updmap.cfg" in "USERTREE/web2c/" is made, and then this
1543 file regenerated from the list of installed packages.
1544 User mode backup, restore, remove, update
1546 In user mode, these actions check that all packages to be acted on are
1547 installed in the user tree before proceeding; otherwise, they behave
1548 just as in normal mode.
1549 User mode generate, option, paper
1551 In user mode, these actions operate only on the user tree's
1552 configuration files and/or "texlive.tlpdb".
1553 User mode logs
1555 In user mode, "tlmgr.log" and <tlmgr-commands.log> are written in the
1556 "TEXMFVAR/web2c/" directlry instead of "TEXMFSYSVAR/web2c/".
1557
1559 The main TeX Live repository contains a vast array of packages.
1560 Nevertheless, additional local repositories can be useful to provide
1561 locally-installed resources, such as proprietary fonts and house
1562 styles. Also, alternative package repositories distribute packages
1563 that cannot or should not be included in TeX Live, for whatever reason.
1564 The simplest and most reliable method is to temporarily set the
1566 installation source to any repository (with the "-repository" or
1567 "option repository" command line options), and perform your operations.
1568 When you are using multiple repositories over a sustained length of
1570 time, however, explicitly switching between them becomes inconvenient.
1571 Thus, it's possible to tell "tlmgr" about additional repositories you
1572 want to use. The basic command is "tlmgr repository add". The rest of
1573 this section explains further.
1574 When using multiple repositories, one of them has to be set as the main
1576 repository, which distributes most of the installed packages. When you
1577 switch from a single repository installation to a multiple repository
1578 installation, the previous sole repository will be set as the main
1579 repository.
1580 By default, even if multiple repositories are configured, packages are
1582 still only installed from the main repository. Thus, simply adding a
1583 second repository does not actually enable installation of anything
1584 from there. You also have to specify which packages should be taken
1585 from the new repository, by specifying so-called ``pinning'' rules,
1586 described next.
1587 Pinning
1589 When a package "foo" is pinned to a repository, a package "foo" in any
1590 other repository, even if it has a higher revision number, will not be
1591 considered an installable candidate.
1592 As mentioned above, by default everything is pinned to the main
1594 repository. Let's now go through an example of setting up a second
1595 repository and enabling updates of a package from it.
1596 First, check that we have support for multiple repositories, and have
1598 only one enabled (as is the case by default):
1599 $ tlmgr repository list
1601 List of repositories (with tags if set):
1602 /var/www/norbert/tlnet
1603 Ok. Let's add the "tlcontrib" repository (this is a real repository
1605 hosted at <http://contrib.texlive.info>) with the tag "tlcontrib":
1606 $ tlmgr repository add http://contrib.texlive.info/current tlcontrib
1608 Check the repository list again:
1610 $ tlmgr repository list
1612 List of repositories (with tags if set):
1613 http://contrib.texlive.info/current (tlcontrib)
1614 /var/www/norbert/tlnet (main)
1615 Now we specify a pinning entry to get the package "classico" from
1617 "tlcontrib":
1618 $ tlmgr pinning add tlcontrib classico
1620 Check that we can find "classico":
1622 $ tlmgr show classico
1624 package: classico
1625 ...
1626 shortdesc: URW Classico fonts
1627 ...
1628 - install "classico":
1630 $ tlmgr install classico
1632 tlmgr: package repositories:
1633 ...
1634 [1/1, ??:??/??:??] install: classico @tlcontrib [737k]
1635 In the output here you can see that the "classico" package has been
1637 installed from the "tlcontrib" repository (@tlcontrib).
1638 Finally, "tlmgr pinning" also supports removing certain or all packages
1640 from a given repository:
1641 $ tlmgr pinning remove tlcontrib classico # remove just classico
1643 $ tlmgr pinning remove tlcontrib --all # take nothing from tlcontrib
1644 A summary of "tlmgr pinning" actions is given above.
1646
1648 The graphical user interface for "tlmgr" requires Perl/Tk
1649 <https://search.cpan.org/search?query=perl%2Ftk>. For Unix-based
1650 systems Perl/Tk (as well as Perl of course) has to be installed outside
1651 of TL. <https://tug.org/texlive/distro.html#perltk> has a list of
1652 invocations for some distros. For Windows the necessary modules are no
1653 longer shipped within TeX Live, so you'll have to have an external Perl
1654 available that includes them.
1655 We are talking here about the GUI built into tlmgr itself, not about
1657 the other tlmgr GUIs, which are: tlshell (Tcl/Tk-based), tlcockpit
1658 (Java-based) and, only on Macs, TeX Live Utility. These are invoked as
1659 separate programs.
1660 The GUI mode of tlmgr is started with the invocation "tlmgr gui";
1662 assuming Tk is loadable, the graphical user interface will be shown.
1663 The main window contains a menu bar, the main display, and a status
1664 area where messages normally shown on the console are displayed.
1665 Within the main display there are three main parts: the "Display
1667 configuration" area, the list of packages, and the action buttons.
1668 Also, at the top right the currently loaded repository is shown; this
1670 also acts as a button and when clicked will try to load the default
1671 repository. To load a different repository, see the "tlmgr" menu item.
1672 Finally, the status area at the bottom of the window gives additional
1674 information about what is going on.
1675 Main display
1677 Display configuration area
1678 The first part of the main display allows you to specify (filter) which
1680 packages are shown. By default, all are shown. Changes here are
1681 reflected right away.
1682 Status
1684 Select whether to show all packages (the default), only those
1685 installed, only those not installed, or only those with update
1686 available.
1687 Category
1689 Select which categories are shown: packages, collections, and/or
1690 schemes. These are briefly explained in the "DESCRIPTION" section
1691 above.
1692 Match
1694 Select packages matching for a specific pattern. By default, this
1695 searches both descriptions and filenames. You can also select a
1696 subset for searching.
1697 Selection
1699 Select packages to those selected, those not selected, or all.
1700 Here, ``selected'' means that the checkbox in the beginning of the
1701 line of a package is ticked.
1702 Display configuration buttons
1704 To the right there are three buttons: select all packages, select
1705 none (a.k.a. deselect all), and reset all these filters to the
1706 defaults, i.e., show all available.
1707 Package list area
1709 The second are of the main display lists all installed packages. If a
1711 repository is loaded, those that are available but not installed are
1712 also listed.
1713 Double clicking on a package line pops up an informational window with
1715 further details: the long description, included files, etc.
1716 Each line of the package list consists of the following items:
1718 a checkbox
1720 Used to select particular packages; some of the action buttons (see
1721 below) work only on the selected packages.
1722 package name
1724 The name (identifier) of the package as given in the database.
1725 local revision (and version)
1727 If the package is installed the TeX Live revision number for the
1728 installed package will be shown. If there is a catalogue version
1729 given in the database for this package, it will be shown in
1730 parentheses. However, the catalogue version, unlike the TL
1731 revision, is not guaranteed to reflect what is actually installed.
1732 remote revision (and version)
1734 If a repository has been loaded the revision of the package in the
1735 repository (if present) is shown. As with the local column, if a
1736 catalogue version is provided it will be displayed. And also as
1737 with the local column, the catalogue version may be stale.
1738 short description
1740 The short description of the package.
1741 Main display action buttons
1743 Below the list of packages are several buttons:
1745 Update all installed
1747 This calls "tlmgr update --all", i.e., tries to update all
1748 available packages. Below this button is a toggle to allow
1749 reinstallation of previously removed packages as part of this
1750 action.
1751 The other four buttons only work on the selected packages, i.e.,
1753 those where the checkbox at the beginning of the package line is
1754 ticked.
1755 Update
1757 Update only the selected packages.
1758 Install
1760 Install the selected packages; acts like "tlmgr install", i.e.,
1761 also installs dependencies. Thus, installing a collection installs
1762 all its constituent packages.
1763 Remove
1765 Removes the selected packages; acts like "tlmgr remove", i.e., it
1766 will also remove dependencies of collections (but not dependencies
1767 of normal packages).
1768 Backup
1770 Makes a backup of the selected packages; acts like "tlmgr backup".
1771 This action needs the option "backupdir" set (see "Options -"
1772 General>).
1773 Menu bar
1775 The following entries can be found in the menu bar:
1776 "tlmgr" menu
1778 The items here load various repositories: the default as specified
1779 in the TeX Live database, the default network repository, the
1780 repository specified on the command line (if any), and an
1781 arbitrarily manually-entered one. Also has the so-necessary "quit"
1782 operation.
1783 "Options menu"
1785 Provides access to several groups of options: "Paper"
1786 (configuration of default paper sizes), "Platforms" (only on Unix,
1787 configuration of the supported/installed platforms), "GUI Language"
1788 (select language used in the GUI interface), and "General"
1789 (everything else).
1790 Several toggles are also here. The first is "Expert options",
1792 which is set by default. If you turn this off, the next time you
1793 start the GUI a simplified screen will be shown that display only
1794 the most important functionality. This setting is saved in the
1795 configuration file of "tlmgr"; see "CONFIGURATION FILE FOR TLMGR"
1796 for details.
1797 The other toggles are all off by default: for debugging output, to
1799 disable the automatic installation of new packages, and to disable
1800 the automatic removal of packages deleted from the server. Playing
1801 with the choices of what is or isn't installed may lead to an
1802 inconsistent TeX Live installation; e.g., when a package is
1803 renamed.
1804 "Actions menu"
1806 Provides access to several actions: update the filename database
1807 (aka "ls-R", "mktexlsr", "texhash"), rebuild all formats
1808 ("fmtutil-sys --all"), update the font map database ("updmap-sys"),
1809 restore from a backup of a package, and use of symbolic links in
1810 system directories (not on Windows).
1811 The final action is to remove the entire TeX Live installation
1813 (also not on Windows).
1814 "Help menu"
1816 Provides access to the TeX Live manual (also on the web at
1817 <https://tug.org/texlive/doc.html>) and the usual ``About'' box.
1818 GUI options
1820 Some generic Perl/Tk options can be specified with "tlmgr gui" to
1821 control the display:
1822 "-background" color
1824 Set background color.
1825 "-font "" fontname fontsize """
1827 Set font, e.g., "tlmgr gui -font "helvetica 18"". The argument to
1828 "-font" must be quoted, i.e., passed as a single string.
1829 "-foreground" color
1831 Set foreground color.
1832 "-geometry" geomspec
1834 Set the X geometry, e.g., "tlmgr gui -geometry 1024x512-0+0"
1835 creates the window of (approximately) the given size in the upper-
1836 right corner of the display.
1837 "-xrm" xresource
1839 Pass the arbitrary X resource string xresource.
1840 A few other obscure options are recognized but not mentioned here. See
1842 the Perl/Tk documentation (<https://search.cpan.org/perldoc?Tk>) for
1843 the complete list, and any X documentation for general information.
1844
1846 With the "--machine-readable" option, "tlmgr" writes to stdout in the
1847 fixed line-oriented format described here, and the usual informational
1848 messages for human consumption are written to stderr (normally they are
1849 written to stdout). The idea is that a program can get all the
1850 information it needs by reading stdout.
1851 Currently this option only applies to the update, install, and "option"
1853 actions.
1854 Machine-readable "update" and "install" output
1856 The output format is as follows:
1857 fieldname "\t" value
1859 ...
1860 "end-of-header"
1861 pkgname status localrev serverrev size runtime esttot
1862 ...
1863 "end-of-updates"
1864 other output from post actions, not in machine readable form
1865 The header section currently has two fields: "location-url" (the
1867 repository source from which updates are being drawn), and
1868 "total-bytes" (the total number of bytes to be downloaded).
1869 The localrev and serverrev fields for each package are the revision
1871 numbers in the local installation and server repository, respectively.
1872 The size field is the number of bytes to be downloaded, i.e., the size
1873 of the compressed tar file for a network installation, not the unpacked
1874 size. The runtime and esttot fields are only present for updated and
1875 auto-install packages, and contain the currently passed time since
1876 start of installation/updates and the estimated total time.
1877 Line endings may be either LF or CRLF depending on the current
1879 platform.
1880 "location-url" location
1882 The location may be a url (including "file:///foo/bar/..."), or a
1883 directory name ("/foo/bar"). It is the package repository from
1884 which the new package information was drawn.
1885 "total-bytes" count
1887 The count is simply a decimal number, the sum of the sizes of all
1888 the packages that need updating or installing (which are listed
1889 subsequently).
1890 Then comes a line with only the literal string "end-of-header".
1892 Each following line until a line with literal string "end-of-updates"
1894 reports on one package. The fields on each line are separated by a
1895 tab. Here are the fields.
1896 pkgname
1898 The TeX Live package identifier, with a possible platform suffix
1899 for executables. For instance, "pdftex" and "pdftex.i386-linux"
1900 are given as two separate packages, one on each line.
1901 status
1903 The status of the package update. One character, as follows:
1904 "d" The package was removed on the server.
1906 "f" The package was removed in the local installation, even
1908 though a collection depended on it. (E.g., the user ran
1909 "tlmgr remove --force".)
1910 "u" Normal update is needed.
1912 "r" Reversed non-update: the locally-installed version is newer
1914 than the version on the server.
1915 "a" Automatically-determined need for installation, the package
1917 is new on the server and is (most probably) part of an
1918 installed collection.
1919 "i" Package will be installed and isn't present in the local
1921 installation (action install).
1922 "I" Package is already present but will be reinstalled (action
1924 install).
1925 localrev
1927 The revision number of the installed package, or "-" if it is not
1928 present locally.
1929 serverrev
1931 The revision number of the package on the server, or "-" if it is
1932 not present on the server.
1933 size
1935 The size in bytes of the package on the server. The sum of all the
1936 package sizes is given in the "total-bytes" header field mentioned
1937 above.
1938 runtime
1940 The run time since start of installations or updates.
1941 esttot
1943 The estimated total time.
1944 Machine-readable "option" output
1946 The output format is as follows:
1947 key "\t" value
1949 If a value is not saved in the database the string "(not set)" is
1951 shown.
1952 If you are developing a program that uses this output, and find that
1954 changes would be helpful, do not hesitate to write the mailing list.
1955
1957 "tlmgr" uses many of the standard TeX environment variables, as
1958 reported by, e.g., "tlmgr conf" ("conf").
1959 In addition, for ease in scripting and debugging, "tlmgr" looks for the
1961 following environment variables. These are not of interest for normal
1962 user installations.
1963 "TEXLIVE_COMPRESSOR"
1965 This variable allows selecting a different compressor program for
1966 backups and intermediate rollback containers. The order of
1967 selection is:
1968 1. If the environment variable "TEXLIVE_COMPRESSOR" is
1970 defined, use it; abort if it doesn't work. Possible values:
1971 "lz4", "gzip", "xz". The necessary options are added
1972 internally.
1973 2. If lz4 is available (either from the system or TL) and
1975 working, use that.
1976 3. If gzip is available (from the system) and working, use
1978 that.
1979 4. If xz is available (either from the system or TL) and
1981 working, use that.
1982 lz4 and gzip are faster in creating tlmgr's local backups, hence
1984 they are preferred. The unconditional use of xz for the tlnet
1985 containers is unaffected, to minimize download sizes.
1986 "TEXLIVE_DOWNLOADER"
1988 "TL_DOWNLOAD_PROGRAM"
1989 "TL_DOWNLOAD_ARGS"
1990 These options allow selecting different download programs then the
1991 ones automatically selected by the installer. The order of
1992 selection is:
1993 1. If the environment variable "TEXLIVE_DOWNLOADER" is
1995 defined, use it; abort if the specified program doesn't
1996 work. Possible values: "lwp", "curl", "wget". The necessary
1997 options are added internally.
1998 2. If the environment variable "TL_DOWNLOAD_PROGRAM" is
2000 defined (can be any value), use it together with
2001 "TL_DOWNLOAD_ARGS"; abort if it doesn't work.
2002 3. If LWP is available and working, use that (by far the most
2004 efficient method, as it supports persistent downloads).
2005 4. If curl is available (from the system) and working, use
2007 that.
2008 5. If wget is available (either from the system or TL) and
2010 working, use that.
2011 TL provides "wget" binaries for platforms where necessary, so some
2013 download method should always be available.
2014 "TEXLIVE_PREFER_OWN"
2016 By default, compression and download programs provided by the
2017 system, i.e., found along "PATH" are preferred over those shipped
2018 with TeX Live.
2019 This can create problems with systems that are too old, and so can
2021 be overridden by setting the environment variable
2022 "TEXLIVE_PREFER_OWN" to 1. In this case, executables shipped with
2023 TL will be preferred.
2024 Extra compression/download programs not provided by TL, such as
2026 gzip, lwp, and curl, are still checked for on the system and used
2027 if available, per the above. "TEXLIVE_PREFER_OWN" only applies when
2028 the program being checked for is shipped with TL, namely the lz4
2029 and xz compressors and wget downloader.
2030 Exception: on Windows, the "tar.exe" shipped with TL is always
2032 used, regardless of any setting.
2033
2035 This script and its documentation were written for the TeX Live
2036 distribution (<https://tug.org/texlive>) and both are licensed under
2037 the GNU General Public License Version 2 or later.
2038 $Id: tlmgr.pl 66236 2023-02-27 21:44:33Z karl $
2040perl v5.34.0 2023-02-27 TLMGR(1)