LaTeX/Installing Extra Packages
Help and Recommendations
Add-on features for LaTeX are known as packages. Dozens of these are pre-installed with LaTeX and can be used in your documents immediately. They should all be stored in subdirectories of texmf/tex/latex named after each package. The directory name "texmf" stands for “TEX and METAFONT”. To find out what other packages are available and what they do, you should use the CTAN search page which includes a link to Graham Williams' comprehensive package catalogue.
A package is a file or collection of files containing extra LaTeX commands and programming which add new styling features or modify those already existing. There are two main file types: class files with .cls extension, and style files with .sty extension. There may be ancillary files as well. When you try to typeset a document which requires a package which is not installed on your system, LaTeX will warn you with an error message that it is missing. You can download updates to packages you already have (both the ones that were installed along with your version of LaTeX as well as ones you added). There is no limit to the number of packages you can have installed on your computer (apart from disk space!), but there is a configurable limit to the number that can be used inside any one LaTeX document at the same time, although it depends on how big each package is. In practice there is no problem in having even a couple of dozen packages active.
Most LaTeX installations come with a large set of pre-installed style packages, so you can use the package manager of the TeX distribution or the one on your system to manage them. See the automatic installation. But many more are available on the net. The main place to look for style packages on the Internet is CTAN. Once you have identified a package you need that is not in your distribution, use the indexes on any CTAN server to find the package you need and the directory where it can be downloaded from. See the manual installation.
If on a system with a package manager or a portage tree, you can often find packages in the repositories. With TeX Live, it is common to have the distribution packed into a few big packages. For example, to install something related to internationalization, you might have to install a package like texlive-lang.
With MikTeX there is a package manager that allows you to pick the package you want individually. As a convenient feature, upon the compilation of a file requiring non-installed packages, MikTeX will automatically prompt to install the missing ones.
With TeX Live manually installed, use tlmgr to manage packages individually.
tlmgr install <package1> <package2> ... tlmgr remove <package1> <package2> ...
The use of tlmgr is covered in the Installation chapter.
If you cannot find the wanted package with any of the previous methods, see the manual installation.
What you need to look for is usually two files, one ending in .dtx and the other in .ins. The first is a DOCTeX file, which combines the package program and its documentation in a single file. The second is the installation routine (much smaller). You must always download both files. If the two files are not there, it means one of two things:
- Either the package is part of a much larger bundle which you shouldn't normally update unless you change LaTeXversion of LaTeX;
- or it's an older or relatively simple package written by an author who did not use a .dtx file.
Download the package files to a temporary directory. There will often be a readme.txt with a brief description of the package. You should of course read this file first.
Installing a package
There are five steps to installing a LaTeX package. (These steps can also be used on the pieces of a complicated package you wrote yourself; in this case, skip straight to Step 3.)
1. Extract the files Run LaTeX on the .ins file. That is, open the file in your editor and process it as if it were a LaTeX document (which it is), or if you prefer, type latex followed by the .ins filename in a command window in your temporary directory. This will extract all the files needed from the .dtx file (which is why you must have both of them present in the temporary directory). Note down or print the names of the files created if there are a lot of them (read the log file if you want to see their names again).
2. Create the documentation Run LaTeX on the .dtx file. You might need to run it twice or more, to get the cross-references right (just like any other LaTeX document). This will create a .dvi file of documentation explaining what the package is for and how to use it. If you prefer to create PDF then run pdfLaTeX instead. If you created a .idx as well, it means that the document contains an index, too. If you want the index to be created properly, follow the steps in the indexing section. Sometimes you will see that a .glo (glossary) file has been produced. Run the following command instead:
makeindex -s gglo.ist -o name.gls name.glo
3. Install the files While the documentation is printing, move or copy the package files from your temporary directory to the right place[s] in your TeX local installation directory tree. Packages installed by hand should always be placed in your "local" directory tree, not in the directory tree containing all the pre-installed packages. This is done to a) prevent your new package accidentally overwriting files in the main TeX directories; and b) avoid your newly-installed files being overwritten when you next update your version of TeX.
For a TDS(TeX Directory Structure)-conformant system, your "local installation directory tree" is a folder and its subfolders. The outermost folder should probably be called texmf-local/ or texmf/. Its location depends on your system:
- MacTeX: Users/username/Library/texmf/.
- Unix-type systems: Usually ~/texmf/.
- MikTeX: Your local directory tree can be any folder you like, as long as you then register it as a user-managed texmf directory (see http://docs.miktex.org/manual/localadditions.html#id573803)
The "right place" sometimes causes confusion, especially if your TeX installation is old or does not conform to the TeX Directory Structure(TDS). For a TDS-conformant system, the "right place" for a LaTeX .sty file is a suitably-named subdirectory of texmf/tex/latex/. "Suitably-named" means sensible and meaningful (and probably short). For a package like paralist, for example, I'd call the directory texmf/tex/latex/paralist.
Often there is just a .sty file to move, but in the case of complex packages there may be more, and they may belong in different locations. For example, new BibTeX packages or font packages will typically have several files to install. This is why it is a good idea to create a sub-directory for the package rather than dump the files into misc along with other unrelated stuff. If there are configuration or other files, read the documentation to find out if there is a special or preferred location to move them to.
|Type||Directory (under texmf/ or texmf-local/)||Description|
|.afm||fonts/afm/foundry/typeface||Adobe Font Metrics for Type 1 fonts|
|.cls||tex/latex/base||Document class file|
|.fd||tex/latex/mfnfss||Font Definition files for METAFONT fonts|
|.fd||tex/latex/psnfss||Font Definition files for PostScript Type 1 fonts|
|.map||fonts/map/||Font mapping files|
|.pfb||fonts/type1/foundry/typeface||PostScript Type 1 outline|
|.sty||tex/latex/packagename||Style file: the normal package content|
|.tex||doc||TeX source for package documentation|
|.tex||tex/plain/packagename||Plain TeX macro files|
|.tfm||fonts/tfm/foundry/typeface||TeX Font Metrics for METAFONT and Type 1 fonts|
|.vf||fonts/vf/foundry/typeface||TeX virtual fonts|
|others||tex/latex/packagename||other types of file unless instructed otherwise|
For most fonts on CTAN, the foundry is public.
4. Update your index Finally, run your TeX indexer program to update the package database. This program comes with every modern version of TeX and has various names depending on the LaTeX distribution you use. (Read the documentation that came with your installation to find out which it is, or consult http://www.tug.org/fonts/fontinstall.html#fndb):
- teTeX, TeX Live, fpTeX: texhash
- web2c: mktexlsr
- MacTeX: MacTeX appears to do this for you.
- MikTeX: initexmf --update-fndb (or use the GUI)
- MiKTeX 2.7 or later versions, installed on Windows XP through Windows 7: Start -> All Programs -> MikTex -> Settings. In Windows 8 use the keyword Settings and choose the option of Settings with the MiKTex logo. In Settings menu choose the first tab and click on Refresh FNDB-button (MikTex will then check the Program Files directory and update the list of File Name DataBase). After that just verify by clicking 'OK'.
||This step is utterly essential, otherwise nothing will work.|
5. Update font maps If your package installed any TrueType or Type 1 fonts, you need to update the font mapping files in addition to updating the index. Your package author should have included a .map file for the fonts. The map updating program is usually some variant on updmap, depending on your distribution:
- TeX Live and MacTeX: updmap --enable Map=mapfile.map (if you installed the files in a personal tree) or updmap-sys --enable Map=mapfile.map (if you installed the files in a system directory).
- MikTeX: Run initexmf --edit-config-file updmap, add the line "Map mapfile.map to the file that opens, then run initexmf --mkmaps.
The reason this process has not been automated widely is that there are still thousands of installations which do not conform to the TDS, such as old shared Unix systems and some Microsoft Windows systems, so there is no way for an installation program to guess where to put the files: you have to know this. There are also systems where the owner, user, or installer has chosen not to follow the recommended TDS directory structure, or is unable to do so for political or security reasons (such as a shared system where she cannot write to a protected directory). The reason for having the texmf-local directory (called texmf.local on some systems) is to provide a place for local modifications or personal updates, especially if you are a user on a shared or managed system (Unix, Linux, VMS, Windows NT/2000/XP, etc.) where you may not have write-access to the main TeX installation directory tree. You can also have a personal texmf subdirectory in your own login directory. Your installation must be configured to look in these directories first, however, so that any updates to standard packages will be found there before the superseded copies in the main texmf tree. All modern TeX installations should do this anyway, but if not, you can edit texmf/web2c/texmf.cnf yourself.
Checking package status
The universal way to check if a file is available to TeX compilers is the command-line tool kpsewhich.
$ kpsewhich tikz /usr/local/texlive/2012/texmf-dist/tex/plain/pgf/frontendlayer/tikz.tex
kpsewhich will actually search for files only, not for packages. It returns the path to the file. For more details on a specific package use the command-line tool tlmgr (TeX Live only):
tlmgr info <package>
The tlmgr tool has lot more options. To consult the documentation:
To find out what commands a package provides (and thus how to use it), you need to read the documentation. In the texmf/doc subdirectory of your installation there should be directories full of .dvi files, one for every package installed. This location is distribution-specific, but is typically found in:
Generally, most of the packages are in the latex subdirectory, although other packages (such as BibTeX and font packages) are found in other subdirectories in doc. The documentation directories have the same name of the package (e.g. amsmath), which generally have one or more relevant documents in a variety of formats (dvi, txt, pdf, etc.). The documents generally have the same name as the package, but there are exceptions (for example, the documentation for amsmath is found at latex/amsmath/amsdoc.dvi). If your installation procedure has not installed the documentation, the DVI files can all be downloaded from CTAN. Before using a package, you should read the documentation carefully, especially the subsection usually called "User Interface", which describes the commands the package makes available. You cannot just guess and hope it will work: you have to read it and find out.
You can usually automatically open any installed package documentation with the texdoc command:
- Alphabetic catalogue
- With brief descriptions
- Topical catalogue with packages sorted systematically
- Hierarchical mirroring the CTAN folder hierarchy