Your support for our advertisers helps cover the cost of hosting, research, and maintenance of this document

Formatting Information — An introduction to typesetting with LATEX

Chapter 3: Plugins and support

Section 3.2: Installing extra classes and packages

You will not need this section if…

  • …you are using MiKTEX, which has a package auto-installer (also applies to ProTEXt)

  • …you are using a system which has the TEX Live Package Manager tlmgr and you have been using it to keep your system up to date.

This section is for people who have neither MiKTEX nor tlmgr, and for those occasions when you need to install an extra, private, experimental, or non-standard package that cannot be installed automatically, or one that is on CTAN but not included in your distribution.

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 (see § B.3.3.7 below). You then need to download the package and install it using the instructions in § 3.2 (this section).

Some TEX distributions can now catch this error, and will download and install the missing class or package for you right there and then, and carry on typesetting as if it had always been there. Currently the best known implementation of this feature is in the MiKTEX distribution for Microsoft Windows (also part of the ProTEXt distribution which is based on it).

In other systems there is the TEX Live Package Manager (tlmgr), which can download and install packages for you, but not in the middle of a LATEX run: you have to stop and run it separately. The tlmgr program is not yet available in all distributions of LATEX, so check your documentation to see if it is working in your version.

(Package Managers like these can also download updates to packages you already have, both the ones that were installed along with your version of LATEX as well as ones you have added. Updates occur when a class or package author finds and fixes a bug, or adds a new feature. All package updates on CTAN are automatically announced on the Usenet newsgroup comp.text.tex.)

There is no limit to the number of packages you can have installed on your computer (apart from disk space). There is probably a limit to the number that can be used inside any one LATEX document at the same time, although it may depend on how big each package is. In practice there is no problem in having even a few dozen packages active (this document uses over 250 of them).

The Comprehensive TEX Archive Network (CTAN) is a repository of TEX and related software from HyperText Transfer Protocol (HTTP) and File Transfer Protocol (FTP) servers worldwide. It contains copies of almost every piece of free software related to TEX and LATEX, and especially, all the public packages and classes.

Private, experimental, or non-standard packages are normally stored on their author’s server, or on a shared resource like GitHub. To use these, you must get the URI of the download page.

(By unfortunate historical accident, both classes and packages are usually managed and stored on CTAN in the same file format (DocTEX: a .dtx filetype) and are referred to generically as ‘packages’ even though some of them contain classes. We have to live with this.)

3.2.1 Downloading packages

CTAN packages are available as .zip files from any CTAN server.

  • some are in TDS format, which is the same directory layout as your TEX installation, so it is faster and easier to use because it unzips directly into your Personal TEX Directory

  • others are just zip files with no directory structure in them: after unzipping, you have to move the files to ‘The Right Places’ yourself;

  • if you prefer, you can download all the needed files one by one and move the files to ‘The Right Places’ yourself.

The TEX Directory Structure

The TEX Directory Structure (TDS) is the set of folders and subfolders used by all modern distributions of TEX and LATEX so that there are known, fixed places where files are stored. The TDS is documented at http://www.tug.org/tds/.

3.2.1.1 Downloading a TDS package zip file

If you go to a package’s CTAN page (http://ctan.org/pkg/name) this will show the package details, and if the package is available in TDS format, there will be a link labelled ‘TDS archive’ with a file ending in .tds.zip.

Download this and unzip it straight into your Personal TEX Directory, where LATEX will find it first, overriding any other version that is installed. The location of your Personal TEX Directory is described in § A.3 below.

MiKTEX (and ProTEXt) users must also run the Refresh FNDB function (see the mediaobject ‘…’ below).

3.2.1.2 Downloading a non-TDS package zip file

If there is no TDS zip file, there will be a prominent link at bottom right labelled ‘Download the contents of this package in one zip archive’ (see the bottom of Figure 3.1 above).

  1. Download the zip file to a temporary directory. Mac and Linux systems already have a /tmp directory for this purpose. On Windows, create a folder for this purpose like Computer\System\Users\your~name\temp (or just use C:\tmp or C:\temp).

  2. Unzip the file into the tex/latex folder of your Personal TEX Directory. It will create a new subfolder in there called after the package name, and put all the package files in it. You can delete the zip file from the temporary directory afterwards as it is no longer needed.

    Font packages need to be unzipped into tex/fonts instead; otherwise the procedure is the same;

  3. For classes and style packages, you MUST complete installation by extracting the .cls or .sty file[s] as shown in § 3.2.2 below.

  4. Ancillary files such as documentation, and (for font packages) the font files, need to be moved to ‘The Right Place’ (see Table 3.1 below).

3.2.1.3 Manual download

If there is no .zip file at all, as will usually be the case off-CTAN and for private packages, what you need to look for is almost always two files, one ending in .dtx and the other in .ins. The first is a DOCTEX file, which combines the package programs and their documentation in a single file. The second is the installation program (much smaller). You MUST always download both these files, if they exist (and maybe others in the download folder). There are two exceptions noted in § 3.2.1.4 below.

3.2.1.4 Other package downloads

If neither the two files nor the package .zip are there, it means one of two things:

  • Either the package is part of a much larger bundle which you SHOULD NOT update yourself unless you are updating your entire LATEX system;

  • or it’s one of a growing number of packages supplied as a single .dtx file alone (no .ins)

  • or it’s one of a few rare or unusual packages still supplied as a single hand-made .sty or .cls file possibly written for the now obsolete LATEX 2.09, or perhaps by an author who has a doctrinal or philosophical objection to using DOCTEX.

Warning

On Unix-based systems (including Mac OS X and GNU/Linux), all you need to do is unzip the TDS zip file into your Personal TEX Directory. On Windows systems running MiKTEX, you MUST reindex your File Name Database (FNDB) (see step 4 below) before LATEX will be able to find the new files.

3.2.2 Installing a class or package manually

There are four steps to installing a non-TDS LATEX class or package:

  1. Extract the class or package files from the .dtx/.ins files

    Use your directory browser or file manager (eg My Computer, Finder, Thunar, Dolphin, etc) to find the subfolder in your Personal TEX Directory below tex/latex into which you unzipped or downloaded the package file[s].

    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 the directory where the file is.

    This will extract all the files needed from the .dtx file (which is why you must have both of them present in the directory).

    Warning

    If this is a non-TDS zip file, or individually-downloaded files, 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 if not already done

    Some packages come with the PDF documentation already there. If so, ignore this step.

    To [re]create the PDF documentation, run LATEX on the .dtx file twice. This will create a .pdf file of documentation explaining what the package is for and how to use it. Two passes through LATEX are needed in order to resolve any internal crossreferences in the text. If there is a BIBTEX file of references, or if you need the Index, you will need to process bibtex, biber, makeindex, or other ancillary programs. I very strongly recommend doing this with the Build menu of your editor, or with the latexmk tool.

  3. Install the files if needed

    This step is only needed if you unzipped and processed the file in some other location (eg your temporary directory), or if the processing extracted more than just the .cls or .sty file. Other types of files belong in different places in the TDS.

    Move the files created in step 1 above to the right subdirectories in your Personal TEX Directory as shown in Table 3.1 below. Always put the files in subdirectories of your Personal TEX Directory, a ) to prevent your new package accidentally overwriting master files in the main TEX directories and b ) to avoid your newly-installed files being overwritten when you next update your version of TEX. Never, never, NEVER put files into your TEX distribution’s main directory tree. If you are a system administrator updating a shared system, however, you SHOULD put the files into the local (shared) TEX directory tree.

    ‘The Right Place’ sometimes causes confusion, especially if your TEX installation is old or does not conform to the TDS. For a TDS-conformant system, ‘The Right Place’ is your Personal TEX Directory tree unless you are a systems manager updating a shared machine, in which case it’s the local TEX directory tree. Your Personal TEX Directory tree is in your home directory (folder):

    • Unix & GNU/Linux systems: ~/texmf/

    • Apple Macintosh OS X: ~/Library/texmf/

    • Windows systems: Computer\System\Users\your~name\texmf (on obsolete Windows systems you can use C:\texmf).

    Create this directory if it does not already exist. You will need to create subdirectories within this directory: see Table 3.1 below.

    Often there is just a .sty file to move but in the case of complex packages there may be more, and they belong in the different locations shown in Table 3.1 below. It is important to create a subdirectory for the package within your Personal TEX Directory, rather than dump the files into misc along with other unrelated stuff.

  4. Shared systems and MIKTEX: update your index

    On Unix & GNU/Linux systems (including Apple Macintosh OS X) you MUST NOT run the TEX indexer program or create an ls-R database in your Personal TEX Directory. These systems search your Personal TEX Directory automatically.

    Otherwise:

    • Windows MIKTEX users (only) MUST use the MIKTEX Administration program to add your new Personal TEX Directory to MIKTEX’s search tree when you first create it.

      After that, each time you update files in there, you MUST run the File Name Database (FNDB) updater in the MIKTEX Administration program, otherwise TEX will never see your newly-installed files.

    • If you are updating a shared system, putting the files into the local TEX directory tree, you MUST run your TEX indexer program afterwards to update the package database.

      This program comes with every modern version of TEX and is variously called texhash, mktexlsr, or even configure, or it might just be a mouse click on a button or menu in your configuration system (like MIKTEX’s). Read the documentation that came with your installation to find out which it is.

On MIKTEX and shared systems

In these installations, you MUST un your TEX indexer program after making changes. See step 4 above for details.

This step is essential, otherwise none of your changes will work.

Table 3.1: Where in your Personal TEX Directory to put files you install manually from packages

  • •  Every user SHOULD have a Personal TEX Directory to put extra stuff into. Create yours now (see § A.3 below).

  • •  If there are configuration or other files (.cnf, .cfg, etc), read the documentation to find out if there is a special or preferred location to move them to.

TypeSubdirectory of texmfDescription
.afmfonts/afm/foundry/typeface/Adobe Font Metrics
.bstbibtex/bst/packagename/BIBTEX style file
.clotex/latex/classname/Document class options
.clstex/latex/classname/Document class file
.dtxtex/latex/packagename/Package DOCTEX file
.dvidoc/packagename/package documentation
.fdtex/latex/mfnfss/METAFONT Font Definition files
.fdtex/latex/psnfss/PostScript Type 1 Font Definition files
.fdtex/latex/typeface/Other Font Definition files
.instex/latex/packagename/Package DOCTEX installer
.jpgtex/generic/JPG images
.logdoc/packagename/package documentation log
.mffonts/source/public/typeface/METAFONT font outlines
.otffonts/opentype/foundry/typeface/OpenType fonts
.pdfdoc/packagename/package documentation
.pfbfonts/type1/foundry/typeface/PostScript Type 1 outlines
.pngtex/generic/PNG images
.stytex/latex/packagename/Package (style) file
.svgtex/generic/SVG images
.tfmfonts/tfm/foundry/typeface/TEX Font Metrics
.ttffonts/truetype/foundry/typeface/TrueType fonts
.vffonts/vf/foundry/typeface/TEX virtual fonts
otherstex/latex/packagename/unless instructed otherwise

Files in your working folder

It is possible just to unzip package files into your current working folder, where your document is, because LATEX will look there first, before looking in your Personal TEX Directory or anywhere else, but it means that if you use LATEX in a different folder for another document, you’ll have to copy all the packages you put in there. Far better to put them all in The Right Place to start with: your Personal TEX Directory.

The tlmgr auto-updater is widely used in TEX Live systems except where TEX has been installed from Debian-based Unix system packages. On Windows and Apple Mac, and on Unix systems where TEX Live has been installed from the TUG DVD or download, tlmgr is the normal way to update packages. The manual process described above is only for those cases where tlmgr cannot be used.

This includes the 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 yourself. 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 policy or security reasons (such as a shared system where she cannot write to a locked disk or directory).

The local texmf directory (usually called texmf-local or texmf.local) is a place for local modifications on a shared or managed multi-user system (such as a server) which will override but otherwise not interfere with the main TEX installation directory. Your installation should already be configured to look in the personal and local directories first, so that any updates to standard packages will be found there before the copies in the main texmf or the local texmf tree. All modern TEX installations do this, but if not, you can edit texmf/web2c/texmf.cnf (or on a shared system, ask your systems manager or support person to do so). There is an example in § A.6 below.

Exercise 3.3 — Install a package

  1. Download and install the latest version of the enumitem package

This implements inline lists, among many other extra features for list formatting.

3.2.3 Creating the TDS structure

If you have a TEX distribution which has an auto-updater like TEX Live (tlmgr) or MiKTEX, you’ll probably never have to update a package manually, so you won’t need this section unless you want to install something from outside CTAN such as a private, corporate, or commercial package or a typeface.

The TEX Directory Structure (TDS) means you can make the subdirectory structure of your Personal TEX Directory the same as that of your main TEX installation. This way you can have all the branches of the tree you need ready for future use.

If you install packages or fonts using a TDS zip file (see § 3.2.1.1 above), this is the directory structure that will be used: look at the subdirectories of texmf/tex/latex/ and texmf/fonts/ in your main TEX installation for examples. LATEX will always use a package or font in your Personal TEX Directory before looking elsewhere.

On Unix & GNU/Linux systems (including Apple Macintosh OS X) it is straightforward to recreate the entire subdirectory structure ready for use. using the commands in the example ‘Replicating the TDS’ below.

Exercise 3.4 — Replicating the TDS

  1. Find the installation directory of your main TEX distribution:

    $ find / -type d -name texmf-dist 2>/dev/null
  2. Change to that directory:

    $ cd /usr/share/texlive/texmf-dist

    (using whatever directory the first command identified)

  3. Replicate its subdirectories:

    $ find . -type d -exec mkdir -p ~/texmf/{} \;

    On a Mac, use ~/Library/texmf instead of ~/texmf.

    The operation may take a minute to complete

Windows appears to provide no way of doing this, but it may be possible using a Powershell script; or you could install Cygwin, which provides you with the standard Unix tools in a Command window.

  1. MiKTEX users note that you cannot process TEX Installer (.ins and .dtx) files inside MiKTEX’s own installation folders: you have to process them elsewhere first, hence the need for a temporary directory. 

  2. For example, there is no separate xcolor.dtx and xcolor.ins for the xcolor package because it forms part of the graphics bundle, which is included with all LATEX systems anyway. Such packages change very rarely, as they form part of the kernel of LATEX and are very stable. You should never try to update these packages in isolation. 

  3. Almost all of these have been updated to work with LATEX, so they should be installed as in step 3 below, but there are a few remaining.