tlmgr user mode

Starting from tomorrow, tlpretest will contain an extension to the TeX Live Manager called User Mode. This one probably one of the most asked features in recent times, that one can use tlmgr to manage arbitrary texmf trees. Although there are still many things to be improved, the current status already allows users to install many packages, even without write access to the main TeX installation.

The TeX Live Manager tlmgr has been since long the main tool for configuration and management of a TeX Live installation. Most importantly, it is the main tool to update package or install new ones.

In contrast to the normal installation of TeX Live from TUG, repackaged versions of TeX Live for distributions (Debian, SuSE, Fedora, …) normally do not ship the tlmgr, as it would interfere with the normal package manager. But since distributions are sometimes lacking behind with updates, users often asked for an option to use tlmgr to install/update packages in their TEXMFHOME.

Well, here it is now.

A short walk through how to do things. So let us assume that you as user do not have write access to the main TeX Live installation.

Initializing the user tree

The first thing to be done is initializing the user tree. By default, the user tree that is to be handled will be TEXMFHOME, which amounts to ~/texmf on Unix-like systems, and %USERPROFILE%/texmf on Windows (afair). If you want to change that, all the following commands also take an additional option --usertree to specify the tree.

The first thing to call is

  tlmgr --init-usertree

which sets up the initial empty TeX Live database and creates necessary files. In case there is already a file in TEXMFHOME/tlpkg/texlive.tlpdb the command will bail out. Other directories generated are TEXMFHOME/web2c and TEXMFHOME/tlpkg/tlpobj.

The initial texlive.tlpdb contains the very same options as the main installation concerning installation source, installation of docfiles and source files, etc. But after the initial setup these options can be changed in the normal way.

Installation of packages

Not all packages can be installed in the user-managed trees. In fact, all the packages that contain files outside the texmf-dist hierarchy will not be installable in user mode. More technically, only those packages tagged as relocatable will be installable in usermode. Looking at the tlpdb of tlpretest I see currently 2369 packages that can be installed in usermode, not bad (you have to search for relocated 1).

Now installation is quite easy:

$ tlmgr --usermode install 12many 2up
tlmgr: package repositories:
        main = /var/www/norbert/tlpretest
        tlptexlive = /var/www/norbert/tlptexlive
[1/2, ??:??/??:??] install: 12many @main [376k]
[2/2, 00:01/00:01] install: 2up @main [66k]
tlmgr: package log updated at /home/norbu/texmf/web2c/tlmgr.log
running mktexlsr ...
done running mktexlsr.

Here I am using a mirror of tlpretest on my hard disc, as well as tlptexlive for Japanese xdvi and metapost.

One can even install whole collections, but only the relocated packages will be installed:

$ tlmgr --usermode install collection-xetex
tlmgr: package repositories:
        main = /var/www/norbert/tlpretest
        tlptexlive = /var/www/norbert/tlptexlive
[1/28, ??:??/??:??] install: arabxetex @main [618k]
[2/28, 00:00/00:00] install: euenc @main [153k]
[3/28, 00:00/00:00] install: fixlatvian @main [123k]
[4/28, 00:01/00:08] install: fontbook @main [1221k]
[5/28, 00:03/00:10] install: fontwrap @main [277k]
[6/28, 00:03/00:09] install: mathspec @main [214k]
[7/28, 00:04/00:11] install: philokalia @main [168k]
[8/28, 00:05/00:12] install: polyglossia @main [520k]
[9/28, 00:05/00:10] install: ptext @main [74k]
[10/28, 00:05/00:10] install: realscripts @main [109k]
[11/28, 00:05/00:10] install: ucharclasses @main [153k]
[12/28, 00:05/00:09] install: unisugar @main [449k]
[13/28, 00:05/00:08] install: xecjk @main [817k]
[14/28, 00:06/00:08] install: xecolor @main [4k]
Package xecyr is not relocatable, cannot install it in user mode!
[15/28, 00:06/00:08] install: xeindex @main [79k]
[16/28, 00:06/00:08] install: xepersian @main [434k]
[17/28, 00:06/00:07] install: xesearch @main [618k]
Package xetex is not relocatable, cannot install it in user mode!
[18/28, 00:06/00:07] install: xetex-def @main [5k]
[19/28, 00:06/00:07] install: xetex-itrans @main [42k]
[20/28, 00:07/00:08] install: xetex-pstricks @main [2k]
[21/28, 00:07/00:08] install: xetex-tibetan @main [9k]
[22/28, 00:07/00:08] install: xetexconfig @main [14k]
[23/28, 00:07/00:08] install: xetexfontinfo @main [3k]
[24/28, 00:07/00:08] install: xltxtra @main [141k]
[25/28, 00:07/00:08] install: xunicode @main [26k]
[26/28, 00:07/00:08] install: collection-xetex @main [1k]
tlmgr: package log updated at /home/norbu/texmf/web2c/tlmgr.log
running mktexlsr ...
done running mktexlsr.
$

Supported operations

Not all operations of the TeX Live Manager are supported in user mode. Here is the current list, the most up-to-date should always be in the documentation of tlmgr, so either to be found in the output of tlmgr help, or on this web page (starting from tomorrow). For now, here is the current list:

• install:
  in usermode the tlmgr action install will check that the package and
  all depending packages are either all relocated, or those that are not
  relocated are already installed in the system installation. If this is
  true it will unpack all containers to be installed into the user tree
  (TEXMFHOME or the value of –user-tree) and add the respective packages
  to the user texlive.tlpdb (creating it if there has non be created till
  now).

  Currently installing a collection installs all depending packages, but
  in contrast to normal mode does not install depending collections. So
  in *normal* mode tlmgr install collection-context would install
  collection-metapost, c-basic, c-documentation-base, too. In *usermode*
  only the packages mentioned in collection-context are installed.

• backup, restore, remove, update:
  in usermode the tlmgr action update will check that all packages to be
  updated are installed in the user tree, otherwise it behaves exactely
  like the system tlmgr.
• option:
  only acts upon the user’s texlive.tlpdb
• paper:
  changes configuration files in user tree
• generate:
  creates configuration files in user tree

Future development

With respect to supported actions in tlmgr, the user mode is already sufficiently developed. What I want to do in future versions is:

• GUI support: currently the tlmgr GUI does not work in user mode. It should work in the very same way, though.
• Independent installation support: support installation of tlmgr and the necessary files without a main TeX Live installation, and use it in the same way automatically in user mode.

Final warning: This is all in very early development. I have tested it on my own machine for a long time, but that does not mean there are no bugs. Please report to the main TeX Live mailing list in case of problems. Or here.