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 [--w32mode=user|admin] add
838 path [--w32mode=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 "--w32mode" 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 "--w32mode" is given,
854 this option determines the path to be adjusted.
855 If the user does not have admin rights, and the option "--w32mode"
857 is not given, and the setting w32_multi_user is off, the user path
858 is changed, while if the setting w32_multi_user is on, a warning is
859 issued that the caller does not have enough privileges.
860 If the user does not have admin rights, and the option "--w32mode"
862 is given, it must be "user" and the user path will be adjusted. If
863 a user without admin rights uses the option "--w32mode admin" a
864 warning is issued that the caller does not have enough privileges.
865 pinning
867 The "pinning" action manages the pinning file, see "Pinning" below.
868 "pinning show"
870 Shows the current pinning data.
871 "pinning add" repo pkgglob...
873 Pins the packages matching the pkgglob(s) to the repository repo.
874 "pinning remove" repo pkgglob...
876 Any packages recorded in the pinning file matching the <pkgglob>s
877 for the given repository repo are removed.
878 "pinning remove repo --all"
880 Remove all pinning data for repository repo.
881 platform
883 platform list|add|remove platform...
884 platform set platform
885 platform set auto
886 "platform list" lists the TeX Live names of all the platforms
887 (a.k.a. architectures), ("i386-linux", ...) available at the
888 package repository.
889 "platform add" platform... adds the executables for each given
891 platform platform to the installation from the repository.
892 "platform remove" platform... removes the executables for each
894 given platform platform from the installation, but keeps the
895 currently running platform in any case.
896 "platform set" platform switches TeX Live to always use the given
898 platform instead of auto detection.
899 "platform set auto" switches TeX Live to auto detection mode for
901 platform.
902 Platform detection is needed to select the proper "xz" and "wget"
904 binaries that are shipped with TeX Live.
905 "arch" is a synonym for "platform".
907 Options:
909 --dry-run
911 Nothing is actually installed; instead, the actions to be
912 performed are written to the terminal.
913 postaction
915 postaction [option...] install [shortcut|fileassoc|script] [pkg...]
916 postaction [option...] remove [shortcut|fileassoc|script] [pkg...]
917 Carry out the postaction "shortcut", "fileassoc", or "script" given
918 as the second required argument in install or remove mode (which is
919 the first required argument), for either the packages given on the
920 command line, or for all if "--all" is given.
921 Options:
923 --w32mode=[user|admin]
925 If the option "--w32mode" is given the value "user", all
926 actions will only be carried out in the user-accessible parts
927 of the registry/filesystem, while the value "admin" selects the
928 system-wide parts of the registry for the file associations.
929 If you do not have enough permissions, using "--w32mode=admin"
930 will not succeed.
931 --fileassocmode=[1|2]
933 "--fileassocmode" specifies the action for file associations.
934 If it is set to 1 (the default), only new associations are
935 added; if it is set to 2, all associations are set to the TeX
936 Live programs. (See also "option fileassocs".)
937 --all
939 Carry out the postactions for all packages
940 print-platform
942 Print the TeX Live identifier for the detected platform
943 (hardware/operating system) combination to standard output, and exit.
944 "--print-arch" is a synonym.
945 print-platform-info
947 Print the TeX Live platform identifier, TL platform long name, and
948 original output from guess.
949 remove [option...] pkg...
951 Remove each pkg specified. Removing a collection removes all package
952 dependencies (unless "--no-depends" is specified), but not any
953 collection dependencies of that collection. However, when removing a
954 package, dependencies are never removed. Options:
955 --all
957 Uninstalls all of TeX Live, asking for confirmation unless
958 "--force" is also specified.
959 --backup
961 --backupdir directory
962 These options behave just as with the update action (q.v.), except
963 they apply to making backups of packages before they are removed.
964 The default is to make such a backup, that is, to save a copy of
965 packages before removal.
966 The "restore" action explains how to restore from a backup.
968 --no-depends
970 Do not remove dependent packages.
971 --no-depends-at-all
973 See above under install (and beware).
974 --force
976 By default, removal of a package or collection that is a dependency
977 of another collection or scheme is not allowed. With this option,
978 the package will be removed unconditionally. Use with care.
979 A package that has been removed using the "--force" option because
981 it is still listed in an installed collection or scheme will not be
982 updated, and will be mentioned as "forcibly removed" in the output
983 of "tlmgr update --list".
984 --dry-run
986 Nothing is actually removed; instead, the actions to be performed
987 are written to the terminal.
988 Except with "--all", this "remove" action does not automatically remove
990 symlinks to executables from system directories; you need to run "tlmgr
991 path remove" ("path") yourself if you remove an individual package with
992 a symlink in a system directory.
993 repository
995 repository list
996 repository list path|url|tag
997 repository add path [tag]
998 repository remove path|tag
999 repository set path[#tag] [path[#tag] ...]
1000 repository status
1001 This action manages the list of repositories. See MULTIPLE
1002 REPOSITORIES below for detailed explanations.
1003 The first form, "repository list", lists all configured
1005 repositories and the respective tags if set. If a path, url, or tag
1006 is given after the "list" keyword, it is interpreted as the source
1007 from which to initialize a TL database and lists the contained
1008 packages. This can also be an otherwise-unused repository, either
1009 local or remote. If the option "--with-platforms" is specified in
1010 addition, for each package the available platforms (if any) are
1011 also listed.
1012 The form "repository add" adds a repository (optionally attaching a
1014 tag) to the list of repositories, while "repository remove" removes
1015 a repository, either by full path/url, or by tag.
1016 The form "repository set" sets the list of available repositories
1018 to the items given on the command line, overwriting previous
1019 settings.
1020 The form "repository status" reports the verification status of the
1022 loaded repositories with the format of one repository per line with
1023 fields separated by a single space:
1024 The tag (which can be the same as the url);
1026 = the url;
1027 = iff machine-readable output is specified, the verification
1029 code (a number);
1030 = a textual description of the verification status, as the last
1032 field extending to the end of line.
1033 That is, in normal (not machine-readable) output, the third field
1035 (numeric verification status) is not present.
1036 In all cases, one of the repositories must be tagged as "main";
1038 otherwise, all operations will fail!
1039 restore
1041 restore [option...] pkg [rev]
1042 restore [option...] --all
1043 Restore a package from a previously-made backup.
1044 If "--all" is given, try to restore the latest revision of all
1046 package backups found in the backup directory.
1047 Otherwise, if neither pkg nor rev are given, list the available
1049 backup revisions for all packages. With pkg given but no rev, list
1050 all available backup revisions of pkg.
1051 When listing available packages, "tlmgr" shows the revision, and in
1053 parenthesis the creation time if available (in format yyyy-mm-dd
1054 hh:mm).
1055 If (and only if) both pkg and a valid revision number rev are
1057 specified, try to restore the package from the specified backup.
1058 Options:
1060 --all
1062 Try to restore the latest revision of all package backups found
1063 in the backup directory. Additional non-option arguments (like
1064 pkg) are not allowed.
1065 --backupdir directory
1067 Specify the directory where the backups are to be found. If not
1068 given it will be taken from the configuration setting in the
1069 TLPDB.
1070 --dry-run
1072 Nothing is actually restored; instead, the actions to be
1073 performed are written to the terminal.
1074 --force
1076 Don't ask questions.
1077 --json
1079 When listing backups, the option "--json" turn on JSON output.
1080 The format is an array of JSON objects ("name", "rev", "date").
1081 For details see "tlpkg/doc/JSON-formats.txt", format
1082 definition: "TLBACKUPS". If both "--json" and "--data" are
1083 given, "--json" takes precedence.
1084 search
1086 search [option...] what
1087 search [option...] --file what
1088 search [option...] --all what
1089 By default, search the names, short descriptions, and long
1090 descriptions of all locally installed packages for the argument
1091 what, interpreted as a (Perl) regular expression.
1092 Options:
1094 --file
1096 List all filenames containing what.
1097 --all
1099 Search everything: package names, descriptions and filenames.
1100 --global
1102 Search the TeX Live Database of the installation medium,
1103 instead of the local installation.
1104 --word
1106 Restrict the search of package names and descriptions (but not
1107 filenames) to match only full words. For example, searching
1108 for "table" with this option will not output packages
1109 containing the word "tables" (unless they also contain the word
1110 "table" on its own).
1111 shell
1113 Starts an interactive mode, where tlmgr prompts for commands. This can
1114 be used directly, or for scripting. The first line of output is
1115 "protocol" n, where n is an unsigned number identifying the protocol
1116 version (currently 1).
1117 In general, tlmgr actions that can be given on the command line
1119 translate to commands in this shell mode. For example, you can say
1120 "update --list" to see what would be updated. The TLPDB is loaded the
1121 first time it is needed (not at the beginning), and used for the rest
1122 of the session.
1123 Besides these actions, a few commands are specific to shell mode:
1125 protocol
1127 Print "protocol n", the current protocol version.
1128 help
1130 Print pointers to this documentation.
1131 version
1133 Print tlmgr version information.
1134 quit, end, bye, byebye, EOF
1136 Exit.
1137 restart
1139 Restart "tlmgr shell" with the original command line; most useful
1140 when developing "tlmgr".
1141 load [local|remote]
1143 Explicitly load the local or remote, respectively, TLPDB.
1144 save
1146 Save the local TLPDB, presumably after other operations have
1147 changed it.
1148 get [var] =item set [var [val]]
1150 Get the value of var, or set it to val. Possible var names:
1151 "debug-translation", "machine-readable", "no-execute-actions",
1152 "require-verification", "verify-downloads", "repository", and
1153 "prompt". All except "repository" and "prompt" are booleans, taking
1154 values 0 and 1, and behave like the corresponding command line
1155 option. The "repository" variable takes a string, and sets the
1156 remote repository location. The "prompt" variable takes a string,
1157 and sets the current default prompt.
1158 If var or then val is not specified, it is prompted for.
1160 show
1162 Synonym for "info".
1163 uninstall
1165 Synonym for remove.
1166 update [option...] [pkg...]
1168 Updates the packages given as arguments to the latest version available
1169 at the installation source. Either "--all" or at least one pkg name
1170 must be specified. Options:
1171 --all
1173 Update all installed packages except for "tlmgr" itself. If updates
1174 to "tlmgr" itself are present, this gives an error, unless also the
1175 option "--force" or "--self" is given. (See below.)
1176 In addition to updating the installed packages, during the update
1178 of a collection the local installation is (by default) synchronized
1179 to the status of the collection on the server, for both additions
1180 and removals.
1181 This means that if a package has been removed on the server (and
1183 thus has also been removed from the respective collection), "tlmgr"
1184 will remove the package in the local installation. This is called
1185 ``auto-remove'' and is announced as such when using the option
1186 "--list". This auto-removal can be suppressed using the option
1187 "--no-auto-remove" (not recommended, see option description).
1188 Analogously, if a package has been added to a collection on the
1190 server that is also installed locally, it will be added to the
1191 local installation. This is called ``auto-install'' and is
1192 announced as such when using the option "--list". This auto-
1193 installation can be suppressed using the option "--no-auto-install"
1194 (also not recommended).
1195 An exception to the collection dependency checks (including the
1197 auto-installation of packages just mentioned) are those that have
1198 been ``forcibly removed'' by you, that is, you called "tlmgr remove
1199 --force" on them. (See the "remove" action documentation.) To
1200 reinstall any such forcibly removed packages use
1201 "--reinstall-forcibly-removed".
1202 To reiterate: automatic removals and additions are entirely
1204 determined by comparison of collections. Thus, if you manually
1205 install an individual package "foo" which is later removed from the
1206 server, "tlmgr" will not notice and will not remove it locally. (It
1207 has to be this way, without major rearchitecture work, because the
1208 tlpdb does not record the repository from which packages come
1209 from.)
1210 If you want to exclude some packages from the current update run
1212 (e.g., due to a slow link), see the "--exclude" option below.
1213 --self
1215 Update "tlmgr" itself (that is, the infrastructure packages) if
1216 updates to it are present. On Windows this includes updates to the
1217 private Perl interpreter shipped inside TeX Live.
1218 If this option is given together with either "--all" or a list of
1220 packages, then "tlmgr" will be updated first and, if this update
1221 succeeds, the new version will be restarted to complete the rest of
1222 the updates.
1223 In short:
1225 tlmgr update --self # update infrastructure only
1227 tlmgr update --self --all # update infrastructure and all packages
1228 tlmgr update --force --all # update all packages but *not* infrastructure
1229 # ... this last at your own risk, not recommended!
1230 --dry-run
1232 Nothing is actually installed; instead, the actions to be performed
1233 are written to the terminal. This is a more detailed report than
1234 "--list".
1235 --list [pkg]
1237 Concisely list the packages which would be updated, newly
1238 installed, or removed, without actually changing anything. If
1239 "--all" is also given, all available updates are listed. If
1240 "--self" is given, but not "--all", only updates to the critical
1241 packages (tlmgr, texlive infrastructure, perl on Windows, etc.)
1242 are listed. If neither "--all" nor "--self" is given, and in
1243 addition no pkg is given, then "--all" is assumed (thus, "tlmgr
1244 update --list" is the same as "tlmgr update --list --all"). If
1245 neither "--all" nor "--self" is given, but specific package names
1246 are given, those packages are checked for updates.
1247 --exclude pkg
1249 Exclude pkg from the update process. If this option is given more
1250 than once, its arguments accumulate.
1251 An argument pkg excludes both the package pkg itself and all its
1253 related platform-specific packages pkg.ARCH. For example,
1254 tlmgr update --all --exclude a2ping
1256 will not update "a2ping", "a2ping.i386-linux", or any other
1258 "a2ping."ARCH package.
1259 If this option specifies a package that would otherwise be a
1261 candidate for auto-installation, auto-removal, or reinstallation of
1262 a forcibly removed package, "tlmgr" quits with an error message.
1263 Excludes are not supported in these circumstances.
1264 This option can also be set permanently in the tlmgr config file
1266 with the key "update-exclude".
1267 --no-auto-remove [pkg...]
1269 By default, "tlmgr" tries to remove packages in an existing
1270 collection which have disappeared on the server, as described above
1271 under "--all". This option prevents such removals, either for all
1272 packages (with "--all"), or for just the given pkg names. This can
1273 lead to an inconsistent TeX installation, since packages are not
1274 infrequently renamed or replaced by their authors. Therefore this
1275 is not recommended.
1276 --no-auto-install [pkg...]
1278 Under normal circumstances "tlmgr" will install packages which are
1279 new on the server, as described above under "--all". This option
1280 prevents any such automatic installation, either for all packages
1281 (with "--all"), or the given pkg names.
1282 Furthermore, after the "tlmgr" run using this has finished, the
1284 packages that would have been auto-installed will be considered as
1285 forcibly removed. So, if "foobar" is the only new package on the
1286 server, then
1287 tlmgr update --all --no-auto-install
1289 is equivalent to
1291 tlmgr update --all
1293 tlmgr remove --force foobar
1294 Again, since packages are sometimes renamed or replaced, using this
1296 option is not recommended.
1297 --reinstall-forcibly-removed
1299 Under normal circumstances "tlmgr" will not install packages that
1300 have been forcibly removed by the user; that is, removed with
1301 "remove --force", or whose installation was prohibited by
1302 "--no-auto-install" during an earlier update.
1303 This option makes "tlmgr" ignore the forcible removals and re-
1305 install all such packages. This can be used to completely
1306 synchronize an installation with the server's idea of what is
1307 available:
1308 tlmgr update --reinstall-forcibly-removed --all
1310 --backup
1312 --backupdir directory
1313 These two options control the creation of backups of packages
1314 before updating; that is, backing up packages as currently
1315 installed. If neither option is given, no backup will made. If
1316 "--backupdir" is given and specifies a writable directory then a
1317 backup will be made in that location. If only "--backup" is given,
1318 then a backup will be made to the directory previously set via the
1319 "option" action (see below). If both are given then a backup will
1320 be made to the specified directory.
1321 You can also set options via the "option" action to automatically
1323 make backups for all packages, and/or keep only a certain number of
1324 backups.
1325 "tlmgr" always makes a temporary backup when updating packages, in
1327 case of download or other failure during an update. In contrast,
1328 the purpose of this "--backup" option is to save a persistent
1329 backup in case the actual content of the update causes problems,
1330 e.g., introduces an TeX incompatibility.
1331 The "restore" action explains how to restore from a backup.
1333 --no-depends
1335 If you call for updating a package normally all depending packages
1336 will also be checked for updates and updated if necessary. This
1337 switch suppresses this behavior.
1338 --no-depends-at-all
1340 See above under install (and beware).
1341 --force
1343 Force update of normal packages, without updating "tlmgr" itself
1344 (unless the "--self" option is also given). Not recommended.
1345 Also, "update --list" is still performed regardless of this option.
1347 If the package on the server is older than the package already
1349 installed (e.g., if the selected mirror is out of date), "tlmgr" does
1350 not downgrade. Also, packages for uninstalled platforms are not
1351 installed.
1352 "tlmgr" saves one copy of the main "texlive.tlpdb" file used for an
1354 update with a suffix representing the repository url, as in
1355 "tlpkg/texlive.tlpdb.main."long-hash-string. Thus, even when many
1356 mirrors are used, only one main "tlpdb" backup is kept. For non-main
1357 repositories, which do not generally have (m)any mirrors, no pruning of
1358 backups is done.
1359 This action does not automatically add or remove new symlinks in system
1361 directories; you need to run "tlmgr" "path" yourself if you are using
1362 this feature and want new symlinks added.
1363
1365 "tlmgr" reads two configuration files: one is system-wide, in
1366 "TEXMFSYSCONFIG/tlmgr/config", and the other is user-specific, in
1367 "TEXMFCONFIG/tlmgr/config". The user-specific one is the default for
1368 the "conf tlmgr" action. (Run "kpsewhich -var-value=TEXMFSYSCONFIG" or
1369 "... TEXMFCONFIG ..." to see the actual directory names.)
1370 A few defaults corresponding to command-line options can be set in
1372 these configuration files. In addition, the system-wide file can
1373 contain a directive to restrict the allowed actions.
1374 In these config files, empty lines and lines starting with # are
1376 ignored. All other lines must look like:
1377 key = value
1379 where the spaces are optional but the "=" is required.
1381 The allowed keys are:
1383 "auto-remove =" 0 or 1 (default 1), same as command-line option.
1385 "gui-expertmode =" 0 or 1 (default 1). This switches between the full
1386 GUI and a simplified GUI with only the most common settings.
1387 "gui-lang =" llcode, with a language code value as with the command-
1388 line option.
1389 "no-checksums =" 0 or 1 (default 0, see below).
1390 "persistent-downloads =" 0 or 1 (default 1), same as command-line
1391 option.
1392 "require-verification =" 0 or 1 (default 0), same as command-line
1393 option.
1394 "tkfontscale =" floating-point number (default 1.0); scaling factor for
1395 fonts in the Tk-based frontends.
1396 "update-exclude =" comma-separated list of packages (no spaces
1397 allowed). Same as the command line option "--exclude" for the "update"
1398 action.
1399 "verify-downloads =" 0 or 1 (default 1), same as command-line option.
1400 The system-wide config file can contain one additional key:
1402 "allowed-actions =" action1[,action2,...] The value is a comma-
1404 separated list (no spaces) of "tlmgr" actions which are allowed to be
1405 executed when "tlmgr" is invoked in system mode (that is, without
1406 "--usermode"). This allows distributors to include "tlmgr" in their
1407 packaging, but allow only a restricted set of actions that do not
1408 interfere with their distro package manager. For native TeX Live
1409 installations, it doesn't make sense to set this.
1410 Finally, the "no-checksums" key needs more explanation. By default,
1412 package checksums computed and stored on the server (in the TLPDB) are
1413 compared to checksums computed locally after downloading.
1414 "no-checksums" disables this process. The checksum algorithm is
1415 SHA-512. Your system must have one of (looked for in this order) the
1416 Perl "Digest::SHA" module, the "openssl" program
1417 (<https://openssl.org>), the "sha512sum" program (from GNU Coreutils,
1418 <https://www.gnu.org/software/coreutils>), or finally the "shasum"
1419 program (just to support old Macs). If none of these are available, a
1420 warning is issued and "tlmgr" proceeds without checking checksums.
1421 "no-checksums" avoids the warning. (Incidentally, other SHA
1422 implementations, such as the pure Perl and pure Lua modules, are much
1423 too slow to be usable in our context.)
1424
1426 "tlmgr" and "install-tl" perform cryptographic verification if
1427 possible. If verification is performed and successful, the programs
1428 report "(verified)" after loading the TLPDB; otherwise, they report
1429 "(not verified)". But either way, by default the installation and/or
1430 updates proceed normally.
1431 If a program named "gpg" is available (that is, found in "PATH"), by
1433 default cryptographic signatures will be checked: we require the main
1434 repository be signed, but not any additional repositories. If "gpg" is
1435 not available, by default signatures are not checked and no
1436 verification is carried out, but "tlmgr" still proceeds normally.
1437 The behavior of the verification can be controlled by the command line
1439 and config file option "verify-repo" which takes one of the following
1440 values: "none", "main", or "all". With "none", no verification
1441 whatsoever is attempted. With "main" (the default) verification is
1442 required only for the main repository, and only if "gpg" is available;
1443 though attempted for all, missing signatures of subsidiary repositories
1444 will not result in an error. Finally, in the case of "all", "gpg" must
1445 be available and all repositories need to be signed.
1446 In all cases, if a signature is checked and fails to verify, an error
1448 is raised.
1449 Cryptographic verification requires checksum checking (described just
1451 above) to succeed, and a working GnuPG ("gpg") program (see below for
1452 search method). Then, unless cryptographic verification has been
1453 disabled, a signature file ("texlive.tlpdb.*.asc") of the checksum file
1454 is downloaded and the signature verified. The signature is created by
1455 the TeX Live Distribution GPG key 0x0D5E5D9106BAB6BC, which in turn is
1456 signed by Karl Berry's key 0x0716748A30D155AD and Norbert Preining's
1457 key 0x6CACA448860CDC13. All of these keys are obtainable from the
1458 standard key servers.
1459 Additional trusted keys can be added using the "key" action.
1461 Configuration of GnuPG invocation
1463 The executable used for GnuPG is searched as follows: If the
1464 environment variable "TL_GNUPG" is set, it is tested and used;
1465 otherwise "gpg" is checked; finally "gpg2" is checked.
1466 Further adaptation of the "gpg" invocation can be made using the two
1468 environment variables "TL_GNUPGHOME", which is passed to "gpg" as the
1469 value for "--homedir", and "TL_GNUPGARGS", which replaces the default
1470 options "--no-secmem-warning --no-permission-warning".
1471
1473 "tlmgr" provides a restricted way, called ``user mode'', to manage
1474 arbitrary texmf trees in the same way as the main installation. For
1475 example, this allows people without write permissions on the
1476 installation location to update/install packages into a tree of their
1477 own.
1478 "tlmgr" is switched into user mode with the command line option
1480 "--usermode". It does not switch automatically, nor is there any
1481 configuration file setting for it. Thus, this option has to be
1482 explicitly given every time user mode is to be activated.
1483 This mode of "tlmgr" works on a user tree, by default the value of the
1485 "TEXMFHOME" variable. This can be overridden with the command line
1486 option "--usertree". In the following when we speak of the user tree
1487 we mean either "TEXMFHOME" or the one given on the command line.
1488 Not all actions are allowed in user mode; "tlmgr" will warn you and not
1490 carry out any problematic actions. Currently not supported (and
1491 probably will never be) is the "platform" action. The "gui" action is
1492 currently not supported, but may be in a future release.
1493 Some "tlmgr" actions don't need any write permissions and thus work the
1495 same in user mode and normal mode. Currently these are: "check",
1496 "help", "list", "print-platform", "print-platform-info", "search",
1497 "show", "version".
1498 On the other hand, most of the actions dealing with package management
1500 do need write permissions, and thus behave differently in user mode, as
1501 described below: "install", "update", "remove", "option", "paper",
1502 "generate", "backup", "restore", "uninstall", "symlinks".
1503 Before using "tlmgr" in user mode, you have to set up the user tree
1505 with the "init-usertree" action. This creates usertree"/web2c" and
1506 usertree"/tlpkg/tlpobj", and a minimal usertree"/tlpkg/texlive.tlpdb".
1507 At that point, you can tell "tlmgr" to do the (supported) actions by
1508 adding the "--usermode" command line option.
1509 In user mode the file usertree"/tlpkg/texlive.tlpdb" contains only the
1511 packages that have been installed into the user tree using "tlmgr",
1512 plus additional options from the ``virtual'' package
1513 "00texlive.installation" (similar to the main installation's
1514 "texlive.tlpdb").
1515 All actions on packages in user mode can only be carried out on
1517 packages that are known as "relocatable". This excludes all packages
1518 containing executables and a few other core packages. Of the 2500 or
1519 so packages currently in TeX Live the vast majority are relocatable and
1520 can be installed into a user tree.
1521 Description of changes of actions in user mode:
1523 User mode install
1525 In user mode, the "install" action checks that the package and all
1526 dependencies are all either relocated or already installed in the
1527 system installation. If this is the case, it unpacks all containers to
1528 be installed into the user tree (to repeat, that's either "TEXMFHOME"
1529 or the value of "--usertree") and add the respective packages to the
1530 user tree's "texlive.tlpdb" (creating it if need be).
1531 Currently installing a collection in user mode installs all dependent
1533 packages, but in contrast to normal mode, does not install dependent
1534 collections. For example, in normal mode "tlmgr install
1535 collection-context" would install "collection-basic" and other
1536 collections, while in user mode, only the packages mentioned in
1537 "collection-context" are installed.
1538 If a package shipping map files is installed in user mode, a backup of
1540 the user's "updmap.cfg" in "USERTREE/web2c/" is made, and then this
1541 file regenerated from the list of installed packages.
1542 User mode backup, restore, remove, update
1544 In user mode, these actions check that all packages to be acted on are
1545 installed in the user tree before proceeding; otherwise, they behave
1546 just as in normal mode.
1547 User mode generate, option, paper
1549 In user mode, these actions operate only on the user tree's
1550 configuration files and/or "texlive.tlpdb".
1551 User mode logs
1553 In user mode, "tlmgr.log" and <tlmgr-commands.log> are written in the
1554 "TEXMFVAR/web2c/" directlry instead of "TEXMFSYSVAR/web2c/".
1555
1557 The main TeX Live repository contains a vast array of packages.
1558 Nevertheless, additional local repositories can be useful to provide
1559 locally-installed resources, such as proprietary fonts and house
1560 styles. Also, alternative package repositories distribute packages
1561 that cannot or should not be included in TeX Live, for whatever reason.
1562 The simplest and most reliable method is to temporarily set the
1564 installation source to any repository (with the "-repository" or
1565 "option repository" command line options), and perform your operations.
1566 When you are using multiple repositories over a sustained length of
1568 time, however, explicitly switching between them becomes inconvenient.
1569 Thus, it's possible to tell "tlmgr" about additional repositories you
1570 want to use. The basic command is "tlmgr repository add". The rest of
1571 this section explains further.
1572 When using multiple repositories, one of them has to be set as the main
1574 repository, which distributes most of the installed packages. When you
1575 switch from a single repository installation to a multiple repository
1576 installation, the previous sole repository will be set as the main
1577 repository.
1578 By default, even if multiple repositories are configured, packages are
1580 still only installed from the main repository. Thus, simply adding a
1581 second repository does not actually enable installation of anything
1582 from there. You also have to specify which packages should be taken
1583 from the new repository, by specifying so-called ``pinning'' rules,
1584 described next.
1585 Pinning
1587 When a package "foo" is pinned to a repository, a package "foo" in any
1588 other repository, even if it has a higher revision number, will not be
1589 considered an installable candidate.
1590 As mentioned above, by default everything is pinned to the main
1592 repository. Let's now go through an example of setting up a second
1593 repository and enabling updates of a package from it.
1594 First, check that we have support for multiple repositories, and have
1596 only one enabled (as is the case by default):
1597 $ tlmgr repository list
1599 List of repositories (with tags if set):
1600 /var/www/norbert/tlnet
1601 Ok. Let's add the "tlcontrib" repository (this is a real repository
1603 hosted at <http://contrib.texlive.info>) with the tag "tlcontrib":
1604 $ tlmgr repository add http://contrib.texlive.info/current tlcontrib
1606 Check the repository list again:
1608 $ tlmgr repository list
1610 List of repositories (with tags if set):
1611 http://contrib.texlive.info/current (tlcontrib)
1612 /var/www/norbert/tlnet (main)
1613 Now we specify a pinning entry to get the package "classico" from
1615 "tlcontrib":
1616 $ tlmgr pinning add tlcontrib classico
1618 Check that we can find "classico":
1620 $ tlmgr show classico
1622 package: classico
1623 ...
1624 shortdesc: URW Classico fonts
1625 ...
1626 - install "classico":
1628 $ tlmgr install classico
1630 tlmgr: package repositories:
1631 ...
1632 [1/1, ??:??/??:??] install: classico @tlcontrib [737k]
1633 In the output here you can see that the "classico" package has been
1635 installed from the "tlcontrib" repository (@tlcontrib).
1636 Finally, "tlmgr pinning" also supports removing certain or all packages
1638 from a given repository:
1639 $ tlmgr pinning remove tlcontrib classico # remove just classico
1641 $ tlmgr pinning remove tlcontrib --all # take nothing from tlcontrib
1642 A summary of "tlmgr pinning" actions is given above.
1644
1646 The graphical user interface for "tlmgr" requires Perl/Tk
1647 <https://search.cpan.org/search?query=perl%2Ftk>. For Unix-based
1648 systems Perl/Tk (as well as Perl of course) has to be installed outside
1649 of TL. <https://tug.org/texlive/distro.html#perltk> has a list of
1650 invocations for some distros. For Windows the necessary modules are no
1651 longer shipped within TeX Live, so you'll have to have an external Perl
1652 available that includes them.
1653 We are talking here about the GUI built into tlmgr itself, not about
1655 the other tlmgr GUIs, which are: tlshell (Tcl/Tk-based), tlcockpit
1656 (Java-based) and, only on Macs, TeX Live Utility. These are invoked as
1657 separate programs.
1658 The GUI mode of tlmgr is started with the invocation "tlmgr gui";
1660 assuming Tk is loadable, the graphical user interface will be shown.
1661 The main window contains a menu bar, the main display, and a status
1662 area where messages normally shown on the console are displayed.
1663 Within the main display there are three main parts: the "Display
1665 configuration" area, the list of packages, and the action buttons.
1666 Also, at the top right the currently loaded repository is shown; this
1668 also acts as a button and when clicked will try to load the default
1669 repository. To load a different repository, see the "tlmgr" menu item.
1670 Finally, the status area at the bottom of the window gives additional
1672 information about what is going on.
1673 Main display
1675 Display configuration area
1676 The first part of the main display allows you to specify (filter) which
1678 packages are shown. By default, all are shown. Changes here are
1679 reflected right away.
1680 Status
1682 Select whether to show all packages (the default), only those
1683 installed, only those not installed, or only those with update
1684 available.
1685 Category
1687 Select which categories are shown: packages, collections, and/or
1688 schemes. These are briefly explained in the "DESCRIPTION" section
1689 above.
1690 Match
1692 Select packages matching for a specific pattern. By default, this
1693 searches both descriptions and filenames. You can also select a
1694 subset for searching.
1695 Selection
1697 Select packages to those selected, those not selected, or all.
1698 Here, ``selected'' means that the checkbox in the beginning of the
1699 line of a package is ticked.
1700 Display configuration buttons
1702 To the right there are three buttons: select all packages, select
1703 none (a.k.a. deselect all), and reset all these filters to the
1704 defaults, i.e., show all available.
1705 Package list area
1707 The second are of the main display lists all installed packages. If a
1709 repository is loaded, those that are available but not installed are
1710 also listed.
1711 Double clicking on a package line pops up an informational window with
1713 further details: the long description, included files, etc.
1714 Each line of the package list consists of the following items:
1716 a checkbox
1718 Used to select particular packages; some of the action buttons (see
1719 below) work only on the selected packages.
1720 package name
1722 The name (identifier) of the package as given in the database.
1723 local revision (and version)
1725 If the package is installed the TeX Live revision number for the
1726 installed package will be shown. If there is a catalogue version
1727 given in the database for this package, it will be shown in
1728 parentheses. However, the catalogue version, unlike the TL
1729 revision, is not guaranteed to reflect what is actually installed.
1730 remote revision (and version)
1732 If a repository has been loaded the revision of the package in the
1733 repository (if present) is shown. As with the local column, if a
1734 catalogue version is provided it will be displayed. And also as
1735 with the local column, the catalogue version may be stale.
1736 short description
1738 The short description of the package.
1739 Main display action buttons
1741 Below the list of packages are several buttons:
1743 Update all installed
1745 This calls "tlmgr update --all", i.e., tries to update all
1746 available packages. Below this button is a toggle to allow
1747 reinstallation of previously removed packages as part of this
1748 action.
1749 The other four buttons only work on the selected packages, i.e.,
1751 those where the checkbox at the beginning of the package line is
1752 ticked.
1753 Update
1755 Update only the selected packages.
1756 Install
1758 Install the selected packages; acts like "tlmgr install", i.e.,
1759 also installs dependencies. Thus, installing a collection installs
1760 all its constituent packages.
1761 Remove
1763 Removes the selected packages; acts like "tlmgr remove", i.e., it
1764 will also remove dependencies of collections (but not dependencies
1765 of normal packages).
1766 Backup
1768 Makes a backup of the selected packages; acts like "tlmgr backup".
1769 This action needs the option "backupdir" set (see "Options -"
1770 General>).
1771 Menu bar
1773 The following entries can be found in the menu bar:
1774 "tlmgr" menu
1776 The items here load various repositories: the default as specified
1777 in the TeX Live database, the default network repository, the
1778 repository specified on the command line (if any), and an
1779 arbitrarily manually-entered one. Also has the so-necessary "quit"
1780 operation.
1781 "Options menu"
1783 Provides access to several groups of options: "Paper"
1784 (configuration of default paper sizes), "Platforms" (only on Unix,
1785 configuration of the supported/installed platforms), "GUI Language"
1786 (select language used in the GUI interface), and "General"
1787 (everything else).
1788 Several toggles are also here. The first is "Expert options",
1790 which is set by default. If you turn this off, the next time you
1791 start the GUI a simplified screen will be shown that display only
1792 the most important functionality. This setting is saved in the
1793 configuration file of "tlmgr"; see "CONFIGURATION FILE FOR TLMGR"
1794 for details.
1795 The other toggles are all off by default: for debugging output, to
1797 disable the automatic installation of new packages, and to disable
1798 the automatic removal of packages deleted from the server. Playing
1799 with the choices of what is or isn't installed may lead to an
1800 inconsistent TeX Live installation; e.g., when a package is
1801 renamed.
1802 "Actions menu"
1804 Provides access to several actions: update the filename database
1805 (aka "ls-R", "mktexlsr", "texhash"), rebuild all formats
1806 ("fmtutil-sys --all"), update the font map database ("updmap-sys"),
1807 restore from a backup of a package, and use of symbolic links in
1808 system directories (not on Windows).
1809 The final action is to remove the entire TeX Live installation
1811 (also not on Windows).
1812 "Help menu"
1814 Provides access to the TeX Live manual (also on the web at
1815 <https://tug.org/texlive/doc.html>) and the usual ``About'' box.
1816 GUI options
1818 Some generic Perl/Tk options can be specified with "tlmgr gui" to
1819 control the display:
1820 "-background" color
1822 Set background color.
1823 "-font "" fontname fontsize """
1825 Set font, e.g., "tlmgr gui -font "helvetica 18"". The argument to
1826 "-font" must be quoted, i.e., passed as a single string.
1827 "-foreground" color
1829 Set foreground color.
1830 "-geometry" geomspec
1832 Set the X geometry, e.g., "tlmgr gui -geometry 1024x512-0+0"
1833 creates the window of (approximately) the given size in the upper-
1834 right corner of the display.
1835 "-xrm" xresource
1837 Pass the arbitrary X resource string xresource.
1838 A few other obscure options are recognized but not mentioned here. See
1840 the Perl/Tk documentation (<https://search.cpan.org/perldoc?Tk>) for
1841 the complete list, and any X documentation for general information.
1842
1844 With the "--machine-readable" option, "tlmgr" writes to stdout in the
1845 fixed line-oriented format described here, and the usual informational
1846 messages for human consumption are written to stderr (normally they are
1847 written to stdout). The idea is that a program can get all the
1848 information it needs by reading stdout.
1849 Currently this option only applies to the update, install, and "option"
1851 actions.
1852 Machine-readable "update" and "install" output
1854 The output format is as follows:
1855 fieldname "\t" value
1857 ...
1858 "end-of-header"
1859 pkgname status localrev serverrev size runtime esttot
1860 ...
1861 "end-of-updates"
1862 other output from post actions, not in machine readable form
1863 The header section currently has two fields: "location-url" (the
1865 repository source from which updates are being drawn), and
1866 "total-bytes" (the total number of bytes to be downloaded).
1867 The localrev and serverrev fields for each package are the revision
1869 numbers in the local installation and server repository, respectively.
1870 The size field is the number of bytes to be downloaded, i.e., the size
1871 of the compressed tar file for a network installation, not the unpacked
1872 size. The runtime and esttot fields are only present for updated and
1873 auto-install packages, and contain the currently passed time since
1874 start of installation/updates and the estimated total time.
1875 Line endings may be either LF or CRLF depending on the current
1877 platform.
1878 "location-url" location
1880 The location may be a url (including "file:///foo/bar/..."), or a
1881 directory name ("/foo/bar"). It is the package repository from
1882 which the new package information was drawn.
1883 "total-bytes" count
1885 The count is simply a decimal number, the sum of the sizes of all
1886 the packages that need updating or installing (which are listed
1887 subsequently).
1888 Then comes a line with only the literal string "end-of-header".
1890 Each following line until a line with literal string "end-of-updates"
1892 reports on one package. The fields on each line are separated by a
1893 tab. Here are the fields.
1894 pkgname
1896 The TeX Live package identifier, with a possible platform suffix
1897 for executables. For instance, "pdftex" and "pdftex.i386-linux"
1898 are given as two separate packages, one on each line.
1899 status
1901 The status of the package update. One character, as follows:
1902 "d" The package was removed on the server.
1904 "f" The package was removed in the local installation, even
1906 though a collection depended on it. (E.g., the user ran
1907 "tlmgr remove --force".)
1908 "u" Normal update is needed.
1910 "r" Reversed non-update: the locally-installed version is newer
1912 than the version on the server.
1913 "a" Automatically-determined need for installation, the package
1915 is new on the server and is (most probably) part of an
1916 installed collection.
1917 "i" Package will be installed and isn't present in the local
1919 installation (action install).
1920 "I" Package is already present but will be reinstalled (action
1922 install).
1923 localrev
1925 The revision number of the installed package, or "-" if it is not
1926 present locally.
1927 serverrev
1929 The revision number of the package on the server, or "-" if it is
1930 not present on the server.
1931 size
1933 The size in bytes of the package on the server. The sum of all the
1934 package sizes is given in the "total-bytes" header field mentioned
1935 above.
1936 runtime
1938 The run time since start of installations or updates.
1939 esttot
1941 The estimated total time.
1942 Machine-readable "option" output
1944 The output format is as follows:
1945 key "\t" value
1947 If a value is not saved in the database the string "(not set)" is
1949 shown.
1950 If you are developing a program that uses this output, and find that
1952 changes would be helpful, do not hesitate to write the mailing list.
1953
1955 "tlmgr" uses many of the standard TeX environment variables, as
1956 reported by, e.g., "tlmgr conf" ("conf").
1957 In addition, for ease in scripting and debugging, "tlmgr" looks for the
1959 following environment variables. These are not of interest for normal
1960 user installations.
1961 "TEXLIVE_COMPRESSOR"
1963 This variable allows selecting a different compressor program for
1964 backups and intermediate rollback containers. The order of
1965 selection is:
1966 1. If the environment variable "TEXLIVE_COMPRESSOR" is
1968 defined, use it; abort if it doesn't work. Possible values:
1969 "lz4", "gzip", "xz". The necessary options are added
1970 internally.
1971 2. If lz4 is available (either from the system or TL) and
1973 working, use that.
1974 3. If gzip is available (from the system) and working, use
1976 that.
1977 4. If xz is available (either from the system or TL) and
1979 working, use that.
1980 lz4 and gzip are faster in creating tlmgr's local backups, hence
1982 they are preferred. The unconditional use of xz for the tlnet
1983 containers is unaffected, to minimize download sizes.
1984 "TEXLIVE_DOWNLOADER"
1986 "TL_DOWNLOAD_PROGRAM"
1987 "TL_DOWNLOAD_ARGS"
1988 These options allow selecting different download programs then the
1989 ones automatically selected by the installer. The order of
1990 selection is:
1991 1. If the environment variable "TEXLIVE_DOWNLOADER" is
1993 defined, use it; abort if the specified program doesn't
1994 work. Possible values: "lwp", "curl", "wget". The necessary
1995 options are added internally.
1996 2. If the environment variable "TL_DOWNLOAD_PROGRAM" is
1998 defined (can be any value), use it together with
1999 "TL_DOWNLOAD_ARGS"; abort if it doesn't work.
2000 3. If LWP is available and working, use that (by far the most
2002 efficient method, as it supports persistent downloads).
2003 4. If curl is available (from the system) and working, use
2005 that.
2006 5. If wget is available (either from the system or TL) and
2008 working, use that.
2009 TL provides "wget" binaries for platforms where necessary, so some
2011 download method should always be available.
2012 "TEXLIVE_PREFER_OWN"
2014 By default, compression and download programs provided by the
2015 system, i.e., found along "PATH" are preferred over those shipped
2016 with TeX Live.
2017 This can create problems with systems that are too old, and so can
2019 be overridden by setting the environment variable
2020 "TEXLIVE_PREFER_OWN" to 1. In this case, executables shipped with
2021 TL will be preferred.
2022 Extra compression/download programs not provided by TL, such as
2024 gzip, lwp, and curl, are still checked for on the system and used
2025 if available, per the above. "TEXLIVE_PREFER_OWN" only applies when
2026 the program being checked for is shipped with TL, namely the lz4
2027 and xz compressors and wget downloader.
2028 Exception: on Windows, the "tar.exe" shipped with TL is always
2030 used, regardless of any setting.
2031
2033 This script and its documentation were written for the TeX Live
2034 distribution (<https://tug.org/texlive>) and both are licensed under
2035 the GNU General Public License Version 2 or later.
2036 $Id: tlmgr.pl 63033 2022-04-15 05:19:42Z preining $
2038perl v5.34.0 2022-04-15 TLMGR(1)