Installing additional LaTeX class and style files

Obtaining LaTeX packages

LaTeX class and style files can frequently be found on the web sites of academic publishing companies, as well as private home pages. However the one-stop shop for them is CTAN, the Comprehensive TeX Archive Network. It offers TeX resources for virtually any purpose: style files for graphics, non-English languages and multi-column layout, as well as utility programs, fonts and bibliography tools working with (La)TeX. The archive is nicely cross-referenced, so if one style file does not work for you, or if you miss a feature, it is easy to find other similar packages. CTAN also contains style files for many academic journals, such as the IEEEtrans package for IEEE transactions. So it is the place to go looking for anything to do with (La)TeX.

TeX search paths

If you use a style file just once, say for one paper, you can simply copy it to the directory in which your .tex file is located. But for frequently used non-standard document classes and style files, copying them around every time you create a new document is a pain. Since TeX automagically finds the letter and article document class files, shouldn't it also be able to find additional classes, provided you install them in the right location? Correct. It can do that, and we will see in the following how you get that installation bit right.

TeX uses the kpathsea library for finding files. The utility for listing kpathsea search paths is kpsepath. (Though in the Web2C implementation of TeX, kpsepath calls the more powerful kpsewhich via the script kpsetool, the basic interface will suffice for our purposes.) Its one required argument is the path type, which in our case is "tex". For the purpose of path searching, class (.cls) and style (.sty) files count as TeX files. kpsepath outputs a colon-separated list of paths which can be rather long, so it is best line-split with tr:

kpsepath tex | tr : '\n'

(If you don't have the GNU coreutils package to which tr belongs, use sed -e 's/:/\n/g' instead.) The command will print out a large number of paths, which come from various sources: header files compiled into kpathsea, configuration files in /etc/texmf/texmf.d, or the environment variable TEXINPUTS. The search paths come in three different forms which indicate how kpathsea should treat them. Paths ending with a double slash are to be searched recursively. If the path is prepended by two exclamation marks, the file system will not be searched. The file ls-R in the given directory will be taken as a file name database containing a recursive listing of that directory. The file system will never be searched for such paths, even if ls-R does not exist! Paths without either double slashes or exclamation marks are searched without recursion.

kpathsea's documentation is available in html, dvi and pdf format, for instance at the TeX user's group. It may also be installed locally by your Linux distribution. On my Ubuntu system, it is part of the package tetex-doc and located in the directory /usr/share/doc/texmf/programs/.

Installing LaTeX packages

Let us assume you have discovered the ultimate document class on CTAN which you are going to use for the rest of your life, or at least for the next few preprints, and wonder where to put it. Look at the output of the kpsepath command above to see which location suits you best. In my experience (on my system) the path list includes paths in one's home directory (~/.texmf-config/...) and the local install directory (/usr/local/share/texmf/...) as well as the standard paths under /usr/share. Depending on who you are and how final the install is to be, you should choose one of these directories. If you do not have administrator access or merely want to test a document class, you will install your LaTeX package in the path under your home directory. If you want to install a supplementary style or class file globally, it should probably go in /usr/local. Putting things in the standard paths is least recommended as they will be clobbered by distribution installs if and when you upgrade. It might make sense if you want to upgrade a package ahead of time of which a newer distribution will anyway ship the new version.

If none of the existing kpathsea paths suits you, either because the three kinds of paths above do not yet exist or because you need an additional one (say, for a network-wide LaTeX resources repository on some NFS server), you have to add a new path. The simplest possibility, open to non-root users and quick for testing, is the TEXINPUTS environment variable. It contains a colon-separated list of paths to be searched by kpathsea. If it ends with a colon, the given paths are prepended to the standard paths from other sources; if it starts with one, they are appended. If it neither starts nor ends with a colon, the contents of the TEXINPUTS variable replace the other search paths, which is probably not what you want. To configure an additional search path permanently, you can add it to the variable TEXMF defined in /etc/texmf/texmf.cnf. (Look before you overwrite; on my system this file is automatically generated by concatenating files in /etc/texmf/texmf.d.)

If you have installed your LaTeX package under a path ending in two slashes or copied a single style file to an "ordinary" path, you are done. However, if you installed in a path prepended by two exclamation marks, you absolutely have to generate or regenerate the ls-R file. To do this, just go to the directory in question and execute the command "mktexlsr .". It will automatically write to the file ls-R in the right format. Alternatively, you can use ls -1ALR, redirect it to ls-R and prepend the following two lines using a text editor:

% ls-R -- filename database for kpathsea; do not change this line.
./:

Debugging

In case your newly installed file is still not found, you will have to use kpsewhich to find out where it is searched for. (Before that, regenerate any relevant ls-R file to make sure it is up to date.) kpsewhich is the all-purpose front-end of the kpathsea library, which is also indirectly called by kpsepath. Its most extensive debug option -debug -1 will cause it to print out everything it does, including how it obtains path lists for all types of files from the configuration files after finding these very files from different built-in paths. Its output will be longer than your terminal's typical number of saved lines, so you are well advised to pipe it:

kpsewhich -debug -1 article.cls 2>&1 | less

At this point you should also read the kpathsea documentation, which describes both some peculiarities in the path search and the options of kpsewhich. The value given after the -debug option is in fact a bit vector in which every bit controls the output of a specific type of information. See the docs.

TOS / Impressum