TeX Live Manager
From TeX on Mac OS X wiki
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/2008
- 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 --allwithout 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
- 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
