TeX Live Manager

From TeX on Mac OS X wiki

Jump to: navigation, search

Open source (GPL)

TeX Live Manager (tlmgr) is a TeX Live utility first introduced in the 2008 release which allows users to update the software in between major (typically annual) releases.

It is used to update packages and utilities included in TeX Live itself - as opposed to any local or personal additions. That is, it updates packages in the main distribution tree (typically /usr/local/texlive/2008) rather than those in the local or personal trees (typically /usr/local/texlive/texmf-local and, in the case of MacTeX, ~/Library/texmf respectively). It thus allows regular updating of packages not manually installed by the installation administrator or user in alternate locations. To be installed or updated packages must be packed as specified by the TeX Live team (similarly to the Windows MikTeX installer).


Warning: Currently tlmgr is not responsible for maintaining or checking any local or personal additions[1] (e.g. packages installed in /usr/local/texlive/2008/texmf-local or ~/Library/texmf). If you have an obsolete version of package sitting in one of these locations, updating a package with tlmgr will have no effect when you typeset because the software will always use a package in local or personal tree in preference to one in the main distribution tree even if the one in the local or personal tree is older. In order to use the updated package, you must manually remove the older package from the local or personal tree.

Another warning: Those who used mpm (which is the UNIX port of the MikTeX Package Manager for Windows), should not use it with TeX Live 2008. mpm and tlmgr are not compatible, and attempting to use both is likely to cause problems. If you have used mpm and now wish to switch to TeX Live Manager, you should remove mpm completely and start with a clean TeX Live installation.

Contents

Background

Before using the TeX Live Manager, it is helpful to understand a little bit about the organisation of TeX Live. In particular, it helps to know the following:

  • the distribution is organised into collections;
  • each collection contains a number of packages;
  • packages include all the familiar packages you might load in the preamble of a document or download from CTAN;
  • a TeX installation - one you have on your Mac, for example - includes a number of collections.

Basic command line usage

First: Update tlmgr

As tlmgr is very new, it is still undergoing rapid development to improve stability and reliability. It may be helpful to archive your MacTeX installer in case you need to revert to the original configuration. Reports of damage resulting from use of the 2008 distributed version have been made to the TeX on Mac mailing list. Thus it is advisable to update the version distributed with MacTeX 2008 to the latest version before running any of the following commands. To do this:

  • Log in to one of the administrator accounts on your Mac.
  • Download update-tlmgr-latest.sh to your Desktop
  • Run the Terminal Application in your Utilities Folder
  • In the terminal, type (or copy and paste) the following and hit return
cd ~/Desktop;sudo sh update-tlmgr-latest.sh 
  • Enter your administrator password when prompted.

Second: Set Your Server

Tlmgr retrieves updates from one of the many CTAN servers. To avoid overloading a particular server tlmgr is usually configured to use a mirror link, mirror.ctan.org, which parcels out requests to different servers. This is usually the default link but it doesn't hurt to set this.

  • In the terminal, type (or copy and paste) the following and hit return
sudo tlmgr option location http://mirror.ctan.org/systems/texlive/tlnet/
  • Enter your administrator password when prompted.

Accessing documentation

Help is available for the TeX Live Manager. To view it type one of the following in a terminal window:

tlmgr --help

or

texdoc tlmgr

Updating the local installation

The single most important command is:

sudo tlmgr update --all

This command compares the collections installed on your machine with those available in a (typically remote) repository. It checks whether the remote version is newer than the installed version. If so, it updates the local version. Because each collection includes a number of packages, an update an update may involve several different types of changes.

What updating a collection may involve:

  • A local package may be updated if the remote collection contains a newer version of the package.
  • A new package may be installed if a package has been added to the collection.
  • A local package may be deleted if it has been removed from the collection.

Because the command makes changes to the main TeX tree in /usr/local, it requires the use of sudo. To actually update your installation, then, you must use

 
sudo -H tlmgr update --all

Some users may prefer or need to use

sudo tlmgr update --all

You should probably use -H unless you have installed fonts in your personal tree (~/Library/texmf) and you are the sole user of your machine. You should be aware, though, that it is possible for customisations in your personal tree to interfere with the update process when -H is not used. You should therefore scrutinise the console output carefully and consider the possibility that something in your personal tree may be responsible if your have problems. For example, I (--Cfr 22:53, 17 October 2008 (UTC)) found that my personal color.cfg prevented two of the standard formats from being regenerated. Using -H to generate them resolved the issue.

What update --all will not do:

  • It will not install new collections (but according to TeX Live team most likely there will be no new collections).
  • It will not install packages which are not part of any collection.
  • It will not install packages which belong to collections not installed locally.

For example, suppose that collection-science is installed locally but collection-latexextra is not. If you have never updated before your local version of collection-science will not include the package gene-logic. When you update, this package will be installed locally. On the other hand, recipe will not be installed because this package was added to collection-latexextra and this collection is not installed locally.

tlmgr is very intelligent: it skips binary files for platforms other than yours.

Some further options

  • To find out if any updates are available for your installation:

tlmgr update --list
  • To list all available packages with a note telling you whether each is installed on your system or not:

tlmgr list
  • To list all packages which are not installed locally, avoiding files unsuitable for OS X and other uninteresting items:

tlmgr list | egrep -v "^i|binary|00|win32|wintools|darwin|scheme-"
  • To preview actions of sudo update --all without actually running it

tlmgr update --all --dry-run
  • The following commands modify your installation and require sudo:

tlmgr update <packagename>
 
tlmgr update --all

tlmgr install <packagename>

tlmgr remove <packagename>

Any of these may be followed by --dry-run. This will show you the commands which would be executed if the option was omitted without actually running of them. The output is less verbose than that from a regular run but the coverage is comprehensive. In this case, sudo is unnecessary as no changes will be made to your installation.

  • Log

/usr/local/texlive/2008/texmf-var/web2c/tlmgr.log

Installing and using the GUI interface

The X11 GUI for tlmgr requires the Perl/Tk module which is not included in OS X. MacTeX 2008 provides an installer for the module, however. Unless you performed a Custom Install and deselected the GUI Applications option, the installer is located in /Applications/TeX/Utilities/TeX Live Manager/, which also includes some documentation.

Installing the Perl/Tk module will enable both the X11 GUI for tlmgr and the X11 GUI relative of texdoc, texdoctk:

TeX Live Manager (tlmgr) and texdoctk

Once Perl/Tk is installed, access TeX Live Manager's X11 GUI by opening an X11 terminal and typing:

tlmgr --gui

More advanced

What is called tlmgr is actually a symbolic link:

/usr/texbin/tlmgr -> /usr/local/texlive/2008/texmf/scripts/texlive/tlmgr.pl

tlmgr has been updated officially to revision 11452:

tlmgr --version 

returns a revision;

Now (Victor Ivrii 10:07, 12 October 2008 (UTC)) if packages are removed from TeX Live (usually due to licensing), tlmgr will remove them from your computer (if you run tlmgr update --all). To avoid this altogether, use:

tlmgr update --all --no-remove

Alternatively, you may designate a backup directory:

tlmgr backup --backupdir dir [--all] [pkg...]

Other useful actions

tlmgr show <packagename>
 
tlmgr search <string>

Notes

  1. Strictly speaking, TeX Live Manager may be used to update additions to TeX Live from a private repository. For this to work, the additional packages would need to be packaged in the format specified by the TeX Live team, just they must be packaged in format specified by the MikTeX team in order to be maintained by the Windows MikTeX package manager.

tlmgr gone rogue - what to do

  • tlmgr - command not found

Check if there are /usr/local/texlive/2008/texmf/scripts/texlive/tlmgr.pl

and symbolic link /usr/texbin/tlmgr -> ../../texmf/scripts/texlive/tlmgr.pl


  • tlmgr reports an error like

Can't locate object method "option" via package "TeXLive::TLPDB" at /usr/local/texlive/2008/bin/universal-darwin/tlmgr line 1088.

Updated advice from Karl Berry:

    • Go to ftp.ctan.org and get

/pub/tex-archive/systems/tlnet/2008/update-tlmgr-latest.sh

Run it. Some MacOSX ftp client corrupt this file, so use standard terminal ftp


  • tlmgr removed bunch of packages

packages sometimes are removed by texlive team but seldom and not in masse Check

 tlmgr list |grep "^i"|wc -l

the answer should be around 1794 under full installation as of 2008:12:10 (the number could increase or decrease but not much. So if there is a "significant" drop in the number, then you can

tlmgr list collections > ~/Desktop/collections

to have all collections listed (there are 85 of them, but we don't need collection-wintools: Windows support programs); open this file in text editor and one-by-one reinstall them

 sudo tlmgr install collection-basic

and go one by one. Some collections are huge, some tiny.

In the end check the number of packages, collections, schemes as before

tlmgr list |grep "^i"|wc -l

Being paranoid

  • As a precaution first run the command with --dry-run to reduce the risk of something unexpected happening and watch messages;
  • Update some of the package management packages before updating other packages:

sudo tlmgr update bin-texlive texlive.infra

and only then

sudo tlmgr update --all

Other resources

Herb Schulz' "Using tlmgr with MacTEX 2008"
Personal tools