tlmgr - TeX Live package manager

tlmgr is the name of the package and configuration manager included in TeX Live. It operates completely separately from any package manager the operating system may provide. The full documentation for tlmgr is available (updated nightly), or you can run tlmgr --help.

If you installed MacTeX, precede the commands below with sudo, since MacTeX installs as root.

Getting updates

Occasionally new versions of tlmgr are released. Your installed tlmgr will notice and ask you to update it before updating anything else. The command to do this is:

tlmgr update --self

After any updates of tlmgr, you can then run, for instance, tlmgr update --all, which will update (including additions and removals) all other packages in your installation that have been changed on the server. Authors frequently release new versions of their work to CTAN, which is propagated into TeX Live.

We maintain a separate history of tlmgr changes.

Disaster recovery

You may end up in a situation where tlmgr itself does not run due to Perl errors, failed updates, tlpdb changes (Unknown directive...), or some other reason. If this happens, the simplest way forward is to download and run update-tlmgr-latest.sh (Unix) or update-tlmgr-latest.exe (Windows). These are self-extracting archives which include all the infrastructure files. Running them should restore tlmgr to a coherent state.

Before running them, be sure your PATH is set to use the current TeX Live bin directory; the recovery archives use kpsewhich from PATH to figure out where to unpack themselves.

Test versions: tlcritical, pretests

You can get the bleeding-edge tlmgr (e.g., because testing was requested and you'd like to try it), from a separate repository named ‘tlcritical’. This directory is updated nightly from the development sources.

The TeX Live Utility on macOS provides a convenient way to try this: hold down the Option key and choose “Install TeX Live Manager From Critical Repository” from the Actions menu.

You can try tlcritical on any platform using tlmgr: the following command will show you what will be updated, along with commentary that updates to tlmgr itself are present (ignore the urls in that commentary).

tlmgr --repository=ftp://tug.org/texlive/tlcritical update --list

To actually do the update, use --self instead of --list; don't forget to keep the explicit --repository option, as given.

If you have trouble connecting to tug.org via ftp, you can also get tlcritical via rsync. First copy it into its own separate directory on your machine, and then tell tlmgr to use that directory:

rsync rsync://tug.org/tlcritical/ /new/local/dir
tlmgr --repository=/new/local/dir update --list

You can switch back to the standard repository by downloading and running update-tlmgr-latest, as described in the disaster recovery section just above.

Another welcome form of testing is trying the pretest which is available for a time before each official release.

Versioned package containers

In November 2019, we switched tlnet and other network repositories to have version numbers in the package container names, such as texlive.infra.r52634.tar.xz instead of just texlive.infra.tar.xz. The unversioned name will be a symlink, so the change is mostly invisible. All packages were made versioned with the TL'20 release.

If you have an installation from October 2019 or earlier and try to update from the current (versioned) tlnet, running the usual tlmgr update --self will result in a sequence of inscrutable errors (relating to the backups which tlmgr makes), starting with something like:

tlchecksum: given file not readable: /tmp/.../texlive.infra.tar.xz

There are two ways to proceed with the update (they are equivalent). One way is to run a tlmgr-update-latest disaster recovery archive as described in the previous section (the version in the current tlnet should work fine). The other way is to do a self-update from a special repository tlverpkg we've created for just this purpose:

tlmgr --repo ftp://tug.org/texlive/tlverpkg update --self

After doing either of the above, regular updates (including self-updates) should work again.

It's our hope that few people will run into this, since the necessary intermediate step was a critical update for several weeks before the versioning of containers was started.

If you wish to host a TL repository on Windows, you'll probably need to dereference the symlinks when you retrieve the files, or you'll see the same kind of error as above.

Contact

Please email bug reports or other comments to the tex-live mailing list (publicly archived).


$Date: 2024/01/21 21:26:48 $; TeX Live;