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 separated list of field names from: "name", "category",
588 "localrev", "remoterev", "shortdesc", "longdesc", "installed",
589 "size", "relocatable", "depends", "cat-version", "cat-date",
590 "cat-license", plus various "cat-contact-*" fields (see below).
591 The "cat-*" fields all come from the TeX Catalogue
593 (<https://ctan.org/pkg/catalogue>). For each, there are two
594 more variants with prefix "l" and "r", e.g., "lcat-version" and
595 "rcat-version", which indicate the local and remote
596 information, respectively. The variants without "l" and "r"
597 show the most current one, which is normally the remote value.
598 The requested packages' information is listed in CSV format,
600 one package per line, and the column information is given by
601 the "itemN". The "depends" column contains the names of all the
602 dependencies separated by ":" characters.
603 At this writing, the "cat-contact-*" fields include: "home",
605 "repository", "support", "bugs", "announce", "development".
606 Each may be empty or a url value. A brief description is on the
607 CTAN upload page for new packages: <https://ctan.org/upload>.
608 --json
610 In case "--json" is specified, the output is a JSON encoded
611 array where each array element is the JSON representation of a
612 single "TLPOBJ" but with additional information. For details
613 see "tlpkg/doc/JSON-formats.txt", format definition:
614 "TLPOBJINFO". If both "--json" and "--data" are given, "--json"
615 takes precedence.
616 init-usertree
618 Sets up a texmf tree for so-called user mode management, either the
619 default user tree ("TEXMFHOME"), or one specified on the command line
620 with "--usertree". See "USER MODE" below.
621 install [option...] pkg...
623 Install each pkg given on the command line, if it is not already
624 installed. It does not touch existing packages; see the "update"
625 action for how to get the latest version of a package.
626 By default this also installs all packages on which the given pkgs are
628 dependent. Options:
629 --dry-run
631 Nothing is actually installed; instead, the actions to be performed
632 are written to the terminal.
633 --file
635 Instead of fetching a package from the installation repository, use
636 the package files given on the command line. These files must be
637 standard TeX Live package files (with contained tlpobj file).
638 --force
640 If updates to "tlmgr" itself (or other parts of the basic
641 infrastructure) are present, "tlmgr" will bail out and not perform
642 the installation unless this option is given. Not recommended.
643 --no-depends
645 Do not install dependencies. (By default, installing a package
646 ensures that all dependencies of this package are fulfilled.)
647 --no-depends-at-all
649 Normally, when you install a package which ships binary files the
650 respective binary package will also be installed. That is, for a
651 package "foo", the package "foo.i386-linux" will also be installed
652 on an "i386-linux" system. This option suppresses this behavior,
653 and also implies "--no-depends". Don't use it unless you are sure
654 of what you are doing.
655 --reinstall
657 Reinstall a package (including dependencies for collections) even
658 if it already seems to be installed (i.e, is present in the TLPDB).
659 This is useful to recover from accidental removal of files in the
660 hierarchy.
661 When re-installing, only dependencies on normal packages are
663 followed (i.e., not those of category Scheme or Collection).
664 --with-doc
666 --with-src
667 While not recommended, the "install-tl" program provides an option
668 to omit installation of all documentation and/or source files. (By
669 default, everything is installed.) After such an installation, you
670 may find that you want the documentation or source files for a
671 given package after all. You can get them by using these options
672 in conjunction with "--reinstall", as in (using the "fontspec"
673 package as the example):
674 tlmgr install --reinstall --with-doc --with-src fontspec
676 This action does not automatically add new symlinks in system
678 directories; you need to run "tlmgr path add" ("path") yourself if you
679 are using this feature and want new symlinks added.
680 key
682 key list
683 key add file
684 key remove keyid
685 The action "key" allows listing, adding and removing additional GPG
686 keys to the set of trusted keys, that is, those that are used to
687 verify the TeX Live databases.
688 With the "list" argument, "key" lists all keys.
690 The "add" argument requires another argument, either a filename or
692 "-" for stdin, from which the key is added. The key is added to the
693 local keyring "GNUPGHOME/repository-keys.gpg", which is normally
694 "tlpkg/gpg/repository-keys.gpg".
695 The "remove" argument requires a key id and removes the requested
697 id from the local keyring.
698 list
700 Synonym for "info".
701 option
703 option [--json] [show]
704 option [--json] showall|help
705 option key [value]
706 The first form, "show", shows the global TeX Live settings currently
708 saved in the TLPDB with a short description and the "key" used for
709 changing it in parentheses.
710 The second form, "showall", is similar, but also shows options which
712 can be defined but are not currently set to any value ("help" is a
713 synonym).
714 Both "show..." forms take an option "--json", which dumps the option
716 information in JSON format. In this case, both forms dump the same
717 data. For the format of the JSON output see
718 "tlpkg/doc/JSON-formats.txt", format definition "TLOPTION".
719 In the third form, with key, if value is not given, the setting for key
721 is displayed. If value is present, key is set to value.
722 Possible values for key are (run "tlmgr option showall" for the
724 definitive list):
725 repository (default package repository),
727 formats (generate formats at installation or update time),
728 postcode (run postinst code blobs)
729 docfiles (install documentation files),
730 srcfiles (install source files),
731 backupdir (default directory for backups),
732 autobackup (number of backups to keep).
733 sys_bin (directory to which executables are linked by the path action)
734 sys_man (directory to which man pages are linked by the path action)
735 sys_info (directory to which Info files are linked by the path action)
736 desktop_integration (Windows-only: create Start menu shortcuts)
737 fileassocs (Windows-only: change file associations)
738 multiuser (Windows-only: install for all users)
739 One common use of "option" is to permanently change the installation to
741 get further updates from the Internet, after originally installing from
742 DVD. To do this, you can run
743 tlmgr option repository https://mirror.ctan.org/systems/texlive/tlnet
745 The "install-tl" documentation has more information about the possible
747 values for "repository". (For backward compatibility, "location" can
748 be used as a synonym for "repository".)
749 If "formats" is set (this is the default), then formats are regenerated
751 when either the engine or the format files have changed. Disable this
752 only when you know how and want to regenerate formats yourself whenever
753 needed (which is often, in practice).
754 The "postcode" option controls execution of per-package
756 postinstallation action code. It is set by default, and again
757 disabling is not likely to be of interest except to developers doing
758 debugging.
759 The "docfiles" and "srcfiles" options control the installation of their
761 respective file groups (documentation, sources; grouping is
762 approximate) per package. By default both are enabled (1). Either or
763 both can be disabled (set to 0) if disk space is limited or for minimal
764 testing installations, etc. When disabled, the respective files are
765 not downloaded at all.
766 The options "autobackup" and "backupdir" determine the defaults for the
768 actions "update", "backup" and "restore". These three actions need a
769 directory in which to read or write the backups. If "--backupdir" is
770 not specified on the command line, the "backupdir" option value is used
771 (if set). The TL installer sets "backupdir" to ".../tlpkg/backups",
772 under the TL root installation directory.
773 The "autobackup" option (de)activates automatic generation of backups.
775 Its value is an integer. If the "autobackup" value is "-1", no backups
776 are removed. If "autobackup" is 0 or more, it specifies the number of
777 backups to keep. Thus, backups are disabled if the value is 0. In the
778 "--clean" mode of the "backup" action this option also specifies the
779 number to be kept. The default value is 1, so that backups are made,
780 but only one backup is kept.
781 To setup "autobackup" to "-1" on the command line, use:
783 tlmgr option -- autobackup -1
785 The "--" avoids having the "-1" treated as an option. (The "--" stops
787 parsing for options at the point where it appears; this is a general
788 feature across most Unix programs.)
789 The "sys_bin", "sys_man", and "sys_info" options are used on Unix
791 systems to control the generation of links for executables, Info files
792 and man pages. See the "path" action for details.
793 The last three options affect behavior on Windows installations. If
795 "desktop_integration" is set, then some packages will install items in
796 a sub-folder of the Start menu for "tlmgr gui", documentation, etc. If
797 "fileassocs" is set, Windows file associations are made (see also the
798 "postaction" action). Finally, if "multiuser" is set, then adaptions
799 to the registry and the menus are done for all users on the system
800 instead of only the current user. All three options are on by default.
801 paper
803 paper [a4|letter]
804 <[xdvi|pdftex|dvips|dvipdfmx|context|psutils] paper [papersize|--list]>
805 paper --json
806 With no arguments ("tlmgr paper"), shows the default paper size setting
808 for all known programs.
809 With one argument (e.g., "tlmgr paper a4"), sets the default for all
811 known programs to that paper size.
812 With a program given as the first argument and no paper size specified
814 (e.g., "tlmgr dvips paper"), shows the default paper size for that
815 program.
816 With a program given as the first argument and a paper size as the last
818 argument (e.g., "tlmgr dvips paper a4"), set the default for that
819 program to that paper size.
820 With a program given as the first argument and "--list" given as the
822 last argument (e.g., "tlmgr dvips paper --list"), shows all valid paper
823 sizes for that program. The first size shown is the default.
824 If "--json" is specified without other options, the paper setup is
826 dumped in JSON format. For the format of JSON output see
827 "tlpkg/doc/JSON-formats.txt", format definition "TLPAPER".
828 Incidentally, this syntax of having a specific program name before the
830 "paper" keyword is unusual. It is inherited from the longstanding
831 "texconfig" script, which supports other configuration settings for
832 some programs, notably "dvips". "tlmgr" does not support those extra
833 settings.
834 path
836 path [--w32mode=user|admin] add
837 path [--w32mode=user|admin] remove
838 On Unix, adds or removes symlinks for executables, man pages, and
839 info pages in the system directories specified by the respective
840 options (see the "option" description above). Does not change any
841 initialization files, either system or personal. Furthermore, any
842 executables added or removed by future updates are not taken care
843 of automatically; this command must be rerun as needed.
844 On Windows, the registry part where the binary directory is added
846 or removed is determined in the following way:
847 If the user has admin rights, and the option "--w32mode" is not
849 given, the setting w32_multi_user determines the location (i.e., if
850 it is on then the system path, otherwise the user path is changed).
851 If the user has admin rights, and the option "--w32mode" is given,
853 this option determines the path to be adjusted.
854 If the user does not have admin rights, and the option "--w32mode"
856 is not given, and the setting w32_multi_user is off, the user path
857 is changed, while if the setting w32_multi_user is on, a warning is
858 issued that the caller does not have enough privileges.
859 If the user does not have admin rights, and the option "--w32mode"
861 is given, it must be "user" and the user path will be adjusted. If
862 a user without admin rights uses the option "--w32mode admin" a
863 warning is issued that the caller does not have enough privileges.
864 pinning
866 The "pinning" action manages the pinning file, see "Pinning" below.
867 "pinning show"
869 Shows the current pinning data.
870 "pinning add" repo pkgglob...
872 Pins the packages matching the pkgglob(s) to the repository repo.
873 "pinning remove" repo pkgglob...
875 Any packages recorded in the pinning file matching the <pkgglob>s
876 for the given repository repo are removed.
877 "pinning remove repo --all"
879 Remove all pinning data for repository repo.
880 platform
882 platform list|add|remove platform...
883 platform set platform
884 platform set auto
885 "platform list" lists the TeX Live names of all the platforms
886 (a.k.a. architectures), ("i386-linux", ...) available at the
887 package repository.
888 "platform add" platform... adds the executables for each given
890 platform platform to the installation from the repository.
891 "platform remove" platform... removes the executables for each
893 given platform platform from the installation, but keeps the
894 currently running platform in any case.
895 "platform set" platform switches TeX Live to always use the given
897 platform instead of auto detection.
898 "platform set auto" switches TeX Live to auto detection mode for
900 platform.
901 Platform detection is needed to select the proper "xz" and "wget"
903 binaries that are shipped with TeX Live.
904 "arch" is a synonym for "platform".
906 Options:
908 --dry-run
910 Nothing is actually installed; instead, the actions to be
911 performed are written to the terminal.
912 postaction
914 postaction [option...] install [shortcut|fileassoc|script] [pkg...]
915 postaction [option...] remove [shortcut|fileassoc|script] [pkg...]
916 Carry out the postaction "shortcut", "fileassoc", or "script" given
917 as the second required argument in install or remove mode (which is
918 the first required argument), for either the packages given on the
919 command line, or for all if "--all" is given.
920 Options:
922 --w32mode=[user|admin]
924 If the option "--w32mode" is given the value "user", all
925 actions will only be carried out in the user-accessible parts
926 of the registry/filesystem, while the value "admin" selects the
927 system-wide parts of the registry for the file associations.
928 If you do not have enough permissions, using "--w32mode=admin"
929 will not succeed.
930 --fileassocmode=[1|2]
932 "--fileassocmode" specifies the action for file associations.
933 If it is set to 1 (the default), only new associations are
934 added; if it is set to 2, all associations are set to the TeX
935 Live programs. (See also "option fileassocs".)
936 --all
938 Carry out the postactions for all packages
939 print-platform
941 Print the TeX Live identifier for the detected platform
942 (hardware/operating system) combination to standard output, and exit.
943 "--print-arch" is a synonym.
944 print-platform-info
946 Print the TeX Live platform identifier, TL platform long name, and
947 original output from guess.
948 remove [option...] pkg...
950 Remove each pkg specified. Removing a collection removes all package
951 dependencies (unless "--no-depends" is specified), but not any
952 collection dependencies of that collection. However, when removing a
953 package, dependencies are never removed. Options:
954 --all
956 Uninstalls all of TeX Live, asking for confirmation unless
957 "--force" is also specified.
958 --backup
960 --backupdir directory
961 These options behave just as with the update action (q.v.), except
962 they apply to making backups of packages before they are removed.
963 The default is to make such a backup, that is, to save a copy of
964 packages before removal.
965 The "restore" action explains how to restore from a backup.
967 --no-depends
969 Do not remove dependent packages.
970 --no-depends-at-all
972 See above under install (and beware).
973 --force
975 By default, removal of a package or collection that is a dependency
976 of another collection or scheme is not allowed. With this option,
977 the package will be removed unconditionally. Use with care.
978 A package that has been removed using the "--force" option because
980 it is still listed in an installed collection or scheme will not be
981 updated, and will be mentioned as "forcibly removed" in the output
982 of "tlmgr update --list".
983 --dry-run
985 Nothing is actually removed; instead, the actions to be performed
986 are written to the terminal.
987 This action does not automatically remove symlinks to executables from
989 system directories; you need to run "tlmgr path remove" ("path")
990 yourself if you are using this feature and want stale symlinks removed.
991 repository
993 repository list
994 repository list path|url|tag
995 repository add path [tag]
996 repository remove path|tag
997 repository set path[#tag] [path[#tag] ...]
998 repository status
999 This action manages the list of repositories. See MULTIPLE
1000 REPOSITORIES below for detailed explanations.
1001 The first form, "repository list", lists all configured
1003 repositories and the respective tags if set. If a path, url, or tag
1004 is given after the "list" keyword, it is interpreted as the source
1005 from which to initialize a TL database and lists the contained
1006 packages. This can also be an otherwise-unused repository, either
1007 local or remote. If the option "--with-platforms" is specified in
1008 addition, for each package the available platforms (if any) are
1009 also listed.
1010 The form "repository add" adds a repository (optionally attaching a
1012 tag) to the list of repositories, while "repository remove" removes
1013 a repository, either by full path/url, or by tag.
1014 The form "repository set" sets the list of available repositories
1016 to the items given on the command line, overwriting previous
1017 settings.
1018 The form "repository status" reports the verification status of the
1020 loaded repositories with the format of one repository per line with
1021 fields separated by a single space:
1022 The tag (which can be the same as the url);
1024 = the url;
1025 = iff machine-readable output is specified, the verification
1027 code (a number);
1028 = a textual description of the verification status, as the last
1030 field extending to the end of line.
1031 That is, in normal (not machine-readable) output, the third field
1033 (numeric verification status) is not present.
1034 In all cases, one of the repositories must be tagged as "main";
1036 otherwise, all operations will fail!
1037 restore
1039 restore [option...] pkg [rev]
1040 restore [option...] --all
1041 Restore a package from a previously-made backup.
1042 If "--all" is given, try to restore the latest revision of all
1044 package backups found in the backup directory.
1045 Otherwise, if neither pkg nor rev are given, list the available
1047 backup revisions for all packages. With pkg given but no rev, list
1048 all available backup revisions of pkg.
1049 When listing available packages, "tlmgr" shows the revision, and in
1051 parenthesis the creation time if available (in format yyyy-mm-dd
1052 hh:mm).
1053 If (and only if) both pkg and a valid revision number rev are
1055 specified, try to restore the package from the specified backup.
1056 Options:
1058 --all
1060 Try to restore the latest revision of all package backups found
1061 in the backup directory. Additional non-option arguments (like
1062 pkg) are not allowed.
1063 --backupdir directory
1065 Specify the directory where the backups are to be found. If not
1066 given it will be taken from the configuration setting in the
1067 TLPDB.
1068 --dry-run
1070 Nothing is actually restored; instead, the actions to be
1071 performed are written to the terminal.
1072 --force
1074 Don't ask questions.
1075 --json
1077 When listing backups, the option "--json" turn on JSON output.
1078 The format is an array of JSON objects ("name", "rev", "date").
1079 For details see "tlpkg/doc/JSON-formats.txt", format
1080 definition: "TLBACKUPS". If both "--json" and "--data" are
1081 given, "--json" takes precedence.
1082 search
1084 search [option...] what
1085 search [option...] --file what
1086 search [option...] --all what
1087 By default, search the names, short descriptions, and long
1088 descriptions of all locally installed packages for the argument
1089 what, interpreted as a (Perl) regular expression.
1090 Options:
1092 --file
1094 List all filenames containing what.
1095 --all
1097 Search everything: package names, descriptions and filenames.
1098 --global
1100 Search the TeX Live Database of the installation medium,
1101 instead of the local installation.
1102 --word
1104 Restrict the search of package names and descriptions (but not
1105 filenames) to match only full words. For example, searching
1106 for "table" with this option will not output packages
1107 containing the word "tables" (unless they also contain the word
1108 "table" on its own).
1109 shell
1111 Starts an interactive mode, where tlmgr prompts for commands. This can
1112 be used directly, or for scripting. The first line of output is
1113 "protocol" n, where n is an unsigned number identifying the protocol
1114 version (currently 1).
1115 In general, tlmgr actions that can be given on the command line
1117 translate to commands in this shell mode. For example, you can say
1118 "update --list" to see what would be updated. The TLPDB is loaded the
1119 first time it is needed (not at the beginning), and used for the rest
1120 of the session.
1121 Besides these actions, a few commands are specific to shell mode:
1123 protocol
1125 Print "protocol n", the current protocol version.
1126 help
1128 Print pointers to this documentation.
1129 version
1131 Print tlmgr version information.
1132 quit, end, bye, byebye, EOF
1134 Exit.
1135 restart
1137 Restart "tlmgr shell" with the original command line; most useful
1138 when developing "tlmgr".
1139 load [local|remote]
1141 Explicitly load the local or remote, respectively, TLPDB.
1142 save
1144 Save the local TLPDB, presumably after other operations have
1145 changed it.
1146 get [var] =item set [var [val]]
1148 Get the value of var, or set it to val. Possible var names:
1149 "debug-translation", "machine-readable", "no-execute-actions",
1150 "require-verification", "verify-downloads", "repository", and
1151 "prompt". All except "repository" and "prompt" are booleans, taking
1152 values 0 and 1, and behave like the corresponding command line
1153 option. The "repository" variable takes a string, and sets the
1154 remote repository location. The "prompt" variable takes a string,
1155 and sets the current default prompt.
1156 If var or then val is not specified, it is prompted for.
1158 show
1160 Synonym for "info".
1161 uninstall
1163 Synonym for remove.
1164 update [option...] [pkg...]
1166 Updates the packages given as arguments to the latest version available
1167 at the installation source. Either "--all" or at least one pkg name
1168 must be specified. Options:
1169 --all
1171 Update all installed packages except for "tlmgr" itself. If updates
1172 to "tlmgr" itself are present, this gives an error, unless also the
1173 option "--force" or "--self" is given. (See below.)
1174 In addition to updating the installed packages, during the update
1176 of a collection the local installation is (by default) synchronized
1177 to the status of the collection on the server, for both additions
1178 and removals.
1179 This means that if a package has been removed on the server (and
1181 thus has also been removed from the respective collection), "tlmgr"
1182 will remove the package in the local installation. This is called
1183 ``auto-remove'' and is announced as such when using the option
1184 "--list". This auto-removal can be suppressed using the option
1185 "--no-auto-remove" (not recommended, see option description).
1186 Analogously, if a package has been added to a collection on the
1188 server that is also installed locally, it will be added to the
1189 local installation. This is called ``auto-install'' and is
1190 announced as such when using the option "--list". This auto-
1191 installation can be suppressed using the option "--no-auto-install"
1192 (also not recommended).
1193 An exception to the collection dependency checks (including the
1195 auto-installation of packages just mentioned) are those that have
1196 been ``forcibly removed'' by you, that is, you called "tlmgr remove
1197 --force" on them. (See the "remove" action documentation.) To
1198 reinstall any such forcibly removed packages use
1199 "--reinstall-forcibly-removed".
1200 To reiterate: automatic removals and additions are entirely
1202 determined by comparison of collections. Thus, if you manually
1203 install an individual package "foo" which is later removed from the
1204 server, "tlmgr" will not notice and will not remove it locally. (It
1205 has to be this way, without major rearchitecture work, because the
1206 tlpdb does not record the repository from which packages come
1207 from.)
1208 If you want to exclude some packages from the current update run
1210 (e.g., due to a slow link), see the "--exclude" option below.
1211 --self
1213 Update "tlmgr" itself (that is, the infrastructure packages) if
1214 updates to it are present. On Windows this includes updates to the
1215 private Perl interpreter shipped inside TeX Live.
1216 If this option is given together with either "--all" or a list of
1218 packages, then "tlmgr" will be updated first and, if this update
1219 succeeds, the new version will be restarted to complete the rest of
1220 the updates.
1221 In short:
1223 tlmgr update --self # update infrastructure only
1225 tlmgr update --self --all # update infrastructure and all packages
1226 tlmgr update --force --all # update all packages but *not* infrastructure
1227 # ... this last at your own risk, not recommended!
1228 --dry-run
1230 Nothing is actually installed; instead, the actions to be performed
1231 are written to the terminal. This is a more detailed report than
1232 "--list".
1233 --list [pkg]
1235 Concisely list the packages which would be updated, newly
1236 installed, or removed, without actually changing anything. If
1237 "--all" is also given, all available updates are listed. If
1238 "--self" is given, but not "--all", only updates to the critical
1239 packages (tlmgr, texlive infrastructure, perl on Windows, etc.)
1240 are listed. If neither "--all" nor "--self" is given, and in
1241 addition no pkg is given, then "--all" is assumed (thus, "tlmgr
1242 update --list" is the same as "tlmgr update --list --all"). If
1243 neither "--all" nor "--self" is given, but specific package names
1244 are given, those packages are checked for updates.
1245 --exclude pkg
1247 Exclude pkg from the update process. If this option is given more
1248 than once, its arguments accumulate.
1249 An argument pkg excludes both the package pkg itself and all its
1251 related platform-specific packages pkg.ARCH. For example,
1252 tlmgr update --all --exclude a2ping
1254 will not update "a2ping", "a2ping.i386-linux", or any other
1256 "a2ping."ARCH package.
1257 If this option specifies a package that would otherwise be a
1259 candidate for auto-installation, auto-removal, or reinstallation of
1260 a forcibly removed package, "tlmgr" quits with an error message.
1261 Excludes are not supported in these circumstances.
1262 This option can also be set permanently in the tlmgr config file
1264 with the key "update-exclude".
1265 --no-auto-remove [pkg...]
1267 By default, "tlmgr" tries to remove packages in an existing
1268 collection which have disappeared on the server, as described above
1269 under "--all". This option prevents such removals, either for all
1270 packages (with "--all"), or for just the given pkg names. This can
1271 lead to an inconsistent TeX installation, since packages are not
1272 infrequently renamed or replaced by their authors. Therefore this
1273 is not recommended.
1274 --no-auto-install [pkg...]
1276 Under normal circumstances "tlmgr" will install packages which are
1277 new on the server, as described above under "--all". This option
1278 prevents any such automatic installation, either for all packages
1279 (with "--all"), or the given pkg names.
1280 Furthermore, after the "tlmgr" run using this has finished, the
1282 packages that would have been auto-installed will be considered as
1283 forcibly removed. So, if "foobar" is the only new package on the
1284 server, then
1285 tlmgr update --all --no-auto-install
1287 is equivalent to
1289 tlmgr update --all
1291 tlmgr remove --force foobar
1292 Again, since packages are sometimes renamed or replaced, using this
1294 option is not recommended.
1295 --reinstall-forcibly-removed
1297 Under normal circumstances "tlmgr" will not install packages that
1298 have been forcibly removed by the user; that is, removed with
1299 "remove --force", or whose installation was prohibited by
1300 "--no-auto-install" during an earlier update.
1301 This option makes "tlmgr" ignore the forcible removals and re-
1303 install all such packages. This can be used to completely
1304 synchronize an installation with the server's idea of what is
1305 available:
1306 tlmgr update --reinstall-forcibly-removed --all
1308 --backup
1310 --backupdir directory
1311 These two options control the creation of backups of packages
1312 before updating; that is, backing up packages as currently
1313 installed. If neither option is given, no backup will made. If
1314 "--backupdir" is given and specifies a writable directory then a
1315 backup will be made in that location. If only "--backup" is given,
1316 then a backup will be made to the directory previously set via the
1317 "option" action (see below). If both are given then a backup will
1318 be made to the specified directory.
1319 You can also set options via the "option" action to automatically
1321 make backups for all packages, and/or keep only a certain number of
1322 backups.
1323 "tlmgr" always makes a temporary backup when updating packages, in
1325 case of download or other failure during an update. In contrast,
1326 the purpose of this "--backup" option is to save a persistent
1327 backup in case the actual content of the update causes problems,
1328 e.g., introduces an TeX incompatibility.
1329 The "restore" action explains how to restore from a backup.
1331 --no-depends
1333 If you call for updating a package normally all depending packages
1334 will also be checked for updates and updated if necessary. This
1335 switch suppresses this behavior.
1336 --no-depends-at-all
1338 See above under install (and beware).
1339 --force
1341 Force update of normal packages, without updating "tlmgr" itself
1342 (unless the "--self" option is also given). Not recommended.
1343 Also, "update --list" is still performed regardless of this option.
1345 If the package on the server is older than the package already
1347 installed (e.g., if the selected mirror is out of date), "tlmgr" does
1348 not downgrade. Also, packages for uninstalled platforms are not
1349 installed.
1350 "tlmgr" saves one copy of the main "texlive.tlpdb" file used for an
1352 update with a suffix representing the repository url, as in
1353 "tlpkg/texlive.tlpdb.main."long-hash-string. Thus, even when many
1354 mirrors are used, only one main "tlpdb" backup is kept. For non-main
1355 repositories, which do not generally have (m)any mirrors, no pruning of
1356 backups is done.
1357 This action does not automatically add or remove new symlinks in system
1359 directories; you need to run "tlmgr" "path" yourself if you are using
1360 this feature and want new symlinks added.
1361
1363 "tlmgr" reads two configuration files: one is system-wide, in
1364 "TEXMFSYSCONFIG/tlmgr/config", and the other is user-specific, in
1365 "TEXMFCONFIG/tlmgr/config". The user-specific one is the default for
1366 the "conf tlmgr" action. (Run "kpsewhich -var-value=TEXMFSYSCONFIG" or
1367 "... TEXMFCONFIG ..." to see the actual directory names.)
1368 A few defaults corresponding to command-line options can be set in
1370 these configuration files. In addition, the system-wide file can
1371 contain a directive to restrict the allowed actions.
1372 In these config files, empty lines and lines starting with # are
1374 ignored. All other lines must look like:
1375 key = value
1377 where the spaces are optional but the "=" is required.
1379 The allowed keys are:
1381 "auto-remove", value 0 or 1 (default 1), same as command-line option.
1383 "gui-expertmode", value 0 or 1 (default 1). This switches between the
1384 full GUI and a simplified GUI with only the most common settings.
1385 "gui-lang" llcode, with a language code value as with the command-line
1386 option.
1387 "no-checksums", value 0 or 1 (default 0, see below).
1388 "persistent-downloads", value 0 or 1 (default 1), same as command-line
1389 option.
1390 "require-verification", value 0 or 1 (default 0), same as command-line
1391 option.
1392 "tkfontscale", value any float. Controls the scaling of fonts in the Tk
1393 based frontends.
1394 "update-exclude", value: comma-separated list of packages (no space
1395 allowed). Same as the command line option "--exclude" for the action
1396 "update".
1397 "verify-downloads", value 0 or 1 (default 1), same as command-line
1398 option.
1399 The system-wide config file can contain one additional key:
1401 "allowed-actions" action1 [,action,...] The value is a comma-separated
1403 list of "tlmgr" actions which are allowed to be executed when "tlmgr"
1404 is invoked in system mode (that is, without "--usermode").
1405 This allows distributors to include the "tlmgr" in their packaging,
1406 but allow only a restricted set of actions that do not interfere
1407 with their distro package manager. For native TeX Live
1408 installations, it doesn't make sense to set this.
1409 The "no-checksums" key needs more explanation. By default, package
1411 checksums computed and stored on the server (in the TLPDB) are compared
1412 to checksums computed locally after downloading. "no-checksums"
1413 disables this process.
1414 The checksum algorithm is SHA-512. Your system must have one of
1416 (looked for in this order) the Perl "Digest::SHA" module, the "openssl"
1417 program (<https://openssl.org>), the "sha512sum" program (from GNU
1418 Coreutils, <https://www.gnu.org/software/coreutils>), or finally the
1419 "shasum" program (just to support old Macs). If none of these are
1420 available, a warning is issued and "tlmgr" proceeds without checking
1421 checksums. (Incidentally, other SHA implementations, such as the pure
1422 Perl and pure Lua modules, are much too slow to be usable in our
1423 context.) "no-checksums" avoids the warning.
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". creates configuration
1551 files in user tree
1552
1554 The main TeX Live repository contains a vast array of packages.
1555 Nevertheless, additional local repositories can be useful to provide
1556 locally-installed resources, such as proprietary fonts and house
1557 styles. Also, alternative package repositories distribute packages
1558 that cannot or should not be included in TeX Live, for whatever reason.
1559 The simplest and most reliable method is to temporarily set the
1561 installation source to any repository (with the "-repository" or
1562 "option repository" command line options), and perform your operations.
1563 When you are using multiple repositories over a sustained length of
1565 time, however, explicitly switching between them becomes inconvenient.
1566 Thus, it's possible to tell "tlmgr" about additional repositories you
1567 want to use. The basic command is "tlmgr repository add". The rest of
1568 this section explains further.
1569 When using multiple repositories, one of them has to be set as the main
1571 repository, which distributes most of the installed packages. When you
1572 switch from a single repository installation to a multiple repository
1573 installation, the previous sole repository will be set as the main
1574 repository.
1575 By default, even if multiple repositories are configured, packages are
1577 still only installed from the main repository. Thus, simply adding a
1578 second repository does not actually enable installation of anything
1579 from there. You also have to specify which packages should be taken
1580 from the new repository, by specifying so-called ``pinning'' rules,
1581 described next.
1582 Pinning
1584 When a package "foo" is pinned to a repository, a package "foo" in any
1585 other repository, even if it has a higher revision number, will not be
1586 considered an installable candidate.
1587 As mentioned above, by default everything is pinned to the main
1589 repository. Let's now go through an example of setting up a second
1590 repository and enabling updates of a package from it.
1591 First, check that we have support for multiple repositories, and have
1593 only one enabled (as is the case by default):
1594 $ tlmgr repository list
1596 List of repositories (with tags if set):
1597 /var/www/norbert/tlnet
1598 Ok. Let's add the "tlcontrib" repository (this is a real repository
1600 hosted at <http://contrib.texlive.info>) with the tag "tlcontrib":
1601 $ tlmgr repository add http://contrib.texlive.info/current tlcontrib
1603 Check the repository list again:
1605 $ tlmgr repository list
1607 List of repositories (with tags if set):
1608 http://contrib.texlive.info/current (tlcontrib)
1609 /var/www/norbert/tlnet (main)
1610 Now we specify a pinning entry to get the package "classico" from
1612 "tlcontrib":
1613 $ tlmgr pinning add tlcontrib classico
1615 Check that we can find "classico":
1617 $ tlmgr show classico
1619 package: classico
1620 ...
1621 shortdesc: URW Classico fonts
1622 ...
1623 - install "classico":
1625 $ tlmgr install classico
1627 tlmgr: package repositories:
1628 ...
1629 [1/1, ??:??/??:??] install: classico @tlcontrib [737k]
1630 In the output here you can see that the "classico" package has been
1632 installed from the "tlcontrib" repository (@tlcontrib).
1633 Finally, "tlmgr pinning" also supports removing certain or all packages
1635 from a given repository:
1636 $ tlmgr pinning remove tlcontrib classico # remove just classico
1638 $ tlmgr pinning remove tlcontrib --all # take nothing from tlcontrib
1639 A summary of "tlmgr pinning" actions is given above.
1641
1643 The graphical user interface for "tlmgr" requires Perl/Tk
1644 <https://search.cpan.org/search?query=perl%2Ftk>. For Unix-based
1645 systems Perl/Tk (as well as Perl of course) has to be installed outside
1646 of TL. <https://tug.org/texlive/distro.html#perltk> has a list of
1647 invocations for some distros. For Windows the necessary modules are no
1648 longer shipped within TeX Live, so you'll have to have an external Perl
1649 available that includes them.
1650 We are talking here about the GUI built into tlmgr itself, not about
1652 the other tlmgr GUIs, which are: tlshell (Tcl/Tk-based), tlcockpit
1653 (Java-based) and, only on Macs, TeX Live Utility. These are invoked as
1654 separate programs.
1655 The GUI mode of tlmgr is started with the invocation "tlmgr gui";
1657 assuming Tk is loadable, the graphical user interface will be shown.
1658 The main window contains a menu bar, the main display, and a status
1659 area where messages normally shown on the console are displayed.
1660 Within the main display there are three main parts: the "Display
1662 configuration" area, the list of packages, and the action buttons.
1663 Also, at the top right the currently loaded repository is shown; this
1665 also acts as a button and when clicked will try to load the default
1666 repository. To load a different repository, see the "tlmgr" menu item.
1667 Finally, the status area at the bottom of the window gives additional
1669 information about what is going on.
1670 Main display
1672 Display configuration area
1673 The first part of the main display allows you to specify (filter) which
1675 packages are shown. By default, all are shown. Changes here are
1676 reflected right away.
1677 Status
1679 Select whether to show all packages (the default), only those
1680 installed, only those not installed, or only those with update
1681 available.
1682 Category
1684 Select which categories are shown: packages, collections, and/or
1685 schemes. These are briefly explained in the "DESCRIPTION" section
1686 above.
1687 Match
1689 Select packages matching for a specific pattern. By default, this
1690 searches both descriptions and filenames. You can also select a
1691 subset for searching.
1692 Selection
1694 Select packages to those selected, those not selected, or all.
1695 Here, ``selected'' means that the checkbox in the beginning of the
1696 line of a package is ticked.
1697 Display configuration buttons
1699 To the right there are three buttons: select all packages, select
1700 none (a.k.a. deselect all), and reset all these filters to the
1701 defaults, i.e., show all available.
1702 Package list area
1704 The second are of the main display lists all installed packages. If a
1706 repository is loaded, those that are available but not installed are
1707 also listed.
1708 Double clicking on a package line pops up an informational window with
1710 further details: the long description, included files, etc.
1711 Each line of the package list consists of the following items:
1713 a checkbox
1715 Used to select particular packages; some of the action buttons (see
1716 below) work only on the selected packages.
1717 package name
1719 The name (identifier) of the package as given in the database.
1720 local revision (and version)
1722 If the package is installed the TeX Live revision number for the
1723 installed package will be shown. If there is a catalogue version
1724 given in the database for this package, it will be shown in
1725 parentheses. However, the catalogue version, unlike the TL
1726 revision, is not guaranteed to reflect what is actually installed.
1727 remote revision (and version)
1729 If a repository has been loaded the revision of the package in the
1730 repository (if present) is shown. As with the local column, if a
1731 catalogue version is provided it will be displayed. And also as
1732 with the local column, the catalogue version may be stale.
1733 short description
1735 The short description of the package.
1736 Main display action buttons
1738 Below the list of packages are several buttons:
1740 Update all installed
1742 This calls "tlmgr update --all", i.e., tries to update all
1743 available packages. Below this button is a toggle to allow
1744 reinstallation of previously removed packages as part of this
1745 action.
1746 The other four buttons only work on the selected packages, i.e.,
1748 those where the checkbox at the beginning of the package line is
1749 ticked.
1750 Update
1752 Update only the selected packages.
1753 Install
1755 Install the selected packages; acts like "tlmgr install", i.e.,
1756 also installs dependencies. Thus, installing a collection installs
1757 all its constituent packages.
1758 Remove
1760 Removes the selected packages; acts like "tlmgr remove", i.e., it
1761 will also remove dependencies of collections (but not dependencies
1762 of normal packages).
1763 Backup
1765 Makes a backup of the selected packages; acts like "tlmgr backup".
1766 This action needs the option "backupdir" set (see "Options -"
1767 General>).
1768 Menu bar
1770 The following entries can be found in the menu bar:
1771 "tlmgr" menu
1773 The items here load various repositories: the default as specified
1774 in the TeX Live database, the default network repository, the
1775 repository specified on the command line (if any), and an
1776 arbitrarily manually-entered one. Also has the so-necessary "quit"
1777 operation.
1778 "Options menu"
1780 Provides access to several groups of options: "Paper"
1781 (configuration of default paper sizes), "Platforms" (only on Unix,
1782 configuration of the supported/installed platforms), "GUI Language"
1783 (select language used in the GUI interface), and "General"
1784 (everything else).
1785 Several toggles are also here. The first is "Expert options",
1787 which is set by default. If you turn this off, the next time you
1788 start the GUI a simplified screen will be shown that display only
1789 the most important functionality. This setting is saved in the
1790 configuration file of "tlmgr"; see "CONFIGURATION FILE FOR TLMGR"
1791 for details.
1792 The other toggles are all off by default: for debugging output, to
1794 disable the automatic installation of new packages, and to disable
1795 the automatic removal of packages deleted from the server. Playing
1796 with the choices of what is or isn't installed may lead to an
1797 inconsistent TeX Live installation; e.g., when a package is
1798 renamed.
1799 "Actions menu"
1801 Provides access to several actions: update the filename database
1802 (aka "ls-R", "mktexlsr", "texhash"), rebuild all formats
1803 ("fmtutil-sys --all"), update the font map database ("updmap-sys"),
1804 restore from a backup of a package, and use of symbolic links in
1805 system directories (not on Windows).
1806 The final action is to remove the entire TeX Live installation
1808 (also not on Windows).
1809 "Help menu"
1811 Provides access to the TeX Live manual (also on the web at
1812 <https://tug.org/texlive/doc.html>) and the usual ``About'' box.
1813 GUI options
1815 Some generic Perl/Tk options can be specified with "tlmgr gui" to
1816 control the display:
1817 "-background" color
1819 Set background color.
1820 "-font "" fontname fontsize """
1822 Set font, e.g., "tlmgr gui -font "helvetica 18"". The argument to
1823 "-font" must be quoted, i.e., passed as a single string.
1824 "-foreground" color
1826 Set foreground color.
1827 "-geometry" geomspec
1829 Set the X geometry, e.g., "tlmgr gui -geometry 1024x512-0+0"
1830 creates the window of (approximately) the given size in the upper-
1831 right corner of the display.
1832 "-xrm" xresource
1834 Pass the arbitrary X resource string xresource.
1835 A few other obscure options are recognized but not mentioned here. See
1837 the Perl/Tk documentation (<https://search.cpan.org/perldoc?Tk>) for
1838 the complete list, and any X documentation for general information.
1839
1841 With the "--machine-readable" option, "tlmgr" writes to stdout in the
1842 fixed line-oriented format described here, and the usual informational
1843 messages for human consumption are written to stderr (normally they are
1844 written to stdout). The idea is that a program can get all the
1845 information it needs by reading stdout.
1846 Currently this option only applies to the update, install, and "option"
1848 actions.
1849 Machine-readable "update" and "install" output
1851 The output format is as follows:
1852 fieldname "\t" value
1854 ...
1855 "end-of-header"
1856 pkgname status localrev serverrev size runtime esttot
1857 ...
1858 "end-of-updates"
1859 other output from post actions, not in machine readable form
1860 The header section currently has two fields: "location-url" (the
1862 repository source from which updates are being drawn), and
1863 "total-bytes" (the total number of bytes to be downloaded).
1864 The localrev and serverrev fields for each package are the revision
1866 numbers in the local installation and server repository, respectively.
1867 The size field is the number of bytes to be downloaded, i.e., the size
1868 of the compressed tar file for a network installation, not the unpacked
1869 size. The runtime and esttot fields are only present for updated and
1870 auto-install packages, and contain the currently passed time since
1871 start of installation/updates and the estimated total time.
1872 Line endings may be either LF or CRLF depending on the current
1874 platform.
1875 "location-url" location
1877 The location may be a url (including "file:///foo/bar/..."), or a
1878 directory name ("/foo/bar"). It is the package repository from
1879 which the new package information was drawn.
1880 "total-bytes" count
1882 The count is simply a decimal number, the sum of the sizes of all
1883 the packages that need updating or installing (which are listed
1884 subsequently).
1885 Then comes a line with only the literal string "end-of-header".
1887 Each following line until a line with literal string "end-of-updates"
1889 reports on one package. The fields on each line are separated by a
1890 tab. Here are the fields.
1891 pkgname
1893 The TeX Live package identifier, with a possible platform suffix
1894 for executables. For instance, "pdftex" and "pdftex.i386-linux"
1895 are given as two separate packages, one on each line.
1896 status
1898 The status of the package update. One character, as follows:
1899 "d" The package was removed on the server.
1901 "f" The package was removed in the local installation, even
1903 though a collection depended on it. (E.g., the user ran
1904 "tlmgr remove --force".)
1905 "u" Normal update is needed.
1907 "r" Reversed non-update: the locally-installed version is newer
1909 than the version on the server.
1910 "a" Automatically-determined need for installation, the package
1912 is new on the server and is (most probably) part of an
1913 installed collection.
1914 "i" Package will be installed and isn't present in the local
1916 installation (action install).
1917 "I" Package is already present but will be reinstalled (action
1919 install).
1920 localrev
1922 The revision number of the installed package, or "-" if it is not
1923 present locally.
1924 serverrev
1926 The revision number of the package on the server, or "-" if it is
1927 not present on the server.
1928 size
1930 The size in bytes of the package on the server. The sum of all the
1931 package sizes is given in the "total-bytes" header field mentioned
1932 above.
1933 runtime
1935 The run time since start of installations or updates.
1936 esttot
1938 The estimated total time.
1939 Machine-readable "option" output
1941 The output format is as follows:
1942 key "\t" value
1944 If a value is not saved in the database the string "(not set)" is
1946 shown.
1947 If you are developing a program that uses this output, and find that
1949 changes would be helpful, do not hesitate to write the mailing list.
1950
1952 "tlmgr" uses many of the standard TeX environment variables, as
1953 reported by, e.g., "tlmgr conf" ("conf").
1954 In addition, for ease in scripting and debugging, "tlmgr" looks for the
1956 following environment variables. These are not of interest for normal
1957 user installations.
1958 "TEXLIVE_COMPRESSOR"
1960 This variable allows selecting a different compressor program for
1961 backups and intermediate rollback containers. The order of
1962 selection is:
1963 1. If the environment variable "TEXLIVE_COMPRESSOR" is
1965 defined, use it; abort if it doesn't work. Possible values:
1966 "lz4", "gzip", "xz". The necessary options are added
1967 internally.
1968 2. If lz4 is available (either from the system or TL) and
1970 working, use that.
1971 3. If gzip is available (from the system) and working, use
1973 that.
1974 4. If xz is available (either from the system or TL) and
1976 working, use that.
1977 lz4 and gzip are faster in creating tlmgr's local backups, hence
1979 they are preferred. The unconditional use of xz for the tlnet
1980 containers is unaffected, to minimize download sizes.
1981 "TEXLIVE_DOWNLOADER"
1983 "TL_DOWNLOAD_PROGRAM"
1984 "TL_DOWNLOAD_ARGS"
1985 These options allow selecting different download programs then the
1986 ones automatically selected by the installer. The order of
1987 selection is:
1988 1. If the environment variable "TEXLIVE_DOWNLOADER" is
1990 defined, use it; abort if the specified program doesn't
1991 work. Possible values: "lwp", "curl", "wget". The necessary
1992 options are added internally.
1993 2. If the environment variable "TL_DOWNLOAD_PROGRAM" is
1995 defined (can be any value), use it together with
1996 "TL_DOWNLOAD_ARGS"; abort if it doesn't work.
1997 3. If LWP is available and working, use that (by far the most
1999 efficient method, as it supports persistent downloads).
2000 4. If curl is available (from the system) and working, use
2002 that.
2003 5. If wget is available (either from the system or TL) and
2005 working, use that.
2006 TL provides "wget" binaries for platforms where necessary, so some
2008 download method should always be available.
2009 "TEXLIVE_PREFER_OWN"
2011 By default, compression and download programs provided by the
2012 system, i.e., found along "PATH" are preferred over those shipped
2013 with TeX Live.
2014 This can create problems with systems that are too old, and so can
2016 be overridden by setting the environment variable
2017 "TEXLIVE_PREFER_OWN" to 1. In this case, executables shipped with
2018 TL will be preferred.
2019 Extra compression/download programs not provided by TL, such as
2021 gzip, lwp, and curl, are still checked for on the system and used
2022 if available, per the above. "TEXLIVE_PREFER_OWN" only applies when
2023 the program being checked for is shipped with TL, namely the lz4
2024 and xz compressors and wget downloader.
2025 Exception: on Windows, the "tar.exe" shipped with TL is always
2027 used, regardless of any setting.
2028
2030 This script and its documentation were written for the TeX Live
2031 distribution (<https://tug.org/texlive>) and both are licensed under
2032 the GNU General Public License Version 2 or later.
2033 $Id: tlmgr.pl 58931 2021-04-20 22:20:56Z karl $
2035perl v5.32.1 2021-04-20 TLMGR(1)