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: Packages and CTAN

Section 3.2: Installing classes and packages

If you’re using a system which has the tlmgr auto-installer, you don’t need this section except for very rare occasions. The TEX Live Package Manager can be used to find, download, and install packages without you needing to know anything about where they come from or where they get put. The rest of this chapter is for people who want to do it by hand.

If you have to install a package manually, you can use the indexes on any CTAN server to find the package you need and the directory where it can be downloaded.

3.2.1 Downloading packages

Some packages are available as ZIP files in TEX Directory Structure (TDS) format, which is faster and more convenient to use. Others are just plain zip files, or you can download all the needed files individually.

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 might have been installed with your distribution. The correct place for your personal TEX directory is described in § A.2.

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’.

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

Unzip it, then move the files into the directories as shown in Table 3.1.

3.2.1.3 Manual download

If there is no ZIP file at all, 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 (and maybe others in the download folder) if there is no ZIP file.

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 normally update yourself unless you are updating your entire LATEX system;

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

On Unix-based systems (including Mac OS X and GNU/Linux), that's all you need to do. On Windows systems running MiKTEX, you MUST reindex your File Name Database (FNDB, see the last step ‘Shared systems and MIKTEX: update your index’) 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 LATEX class or package:

  1. Extract the class or package files

    Use your directory browser of file manager (eg My Computer, Finder, Thunar, Dolphin, etc) to find the folder where you unzipped or downloaded the .dtx and .ins 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 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).

    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

    Run PDFLATEX 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 (a feature we’ll come onto later). 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

    This step is not needed if you used a TDS zip file.

    Move the files created in the step ‘Extract the class or package files’ from your temporary directory to the right subdirectories in your personal TEX directory (see below). Always put the files in your ‘personal’ TEX directory tree, 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 updating a shared system, however, you can put the files into the local (shared) TEX directory tree.)

    Table 3.1: Where to put files from packages

    TypeSubdirectoryDescription
    .clstex/latex/classnameDocument class file
    .stytex/latex/packagenamePackage (style) file
    .bstbibtex/bst/packagenameBIBTEX style file
    .dvidoc/packagenamepackage documentation
    .pdfdoc/packagenamepackage documentation
    .fdtex/latex/mfnfssFont Definition files for METAFONT fonts
    .fdtex/latex/psnfssFont Definition files for PostScript Type 1 fonts
    .fdtex/latex/packagenameFont Definition files for other fonts
    .mffonts/source/public/typefaceMETAFONT font outline
    .pfbfonts/type1/foundry/typefacePostScript Type 1 outline
    .ttffonts/truetype/foundryTrueType font files
    .otffonts/opentype/foundryOpenType font files
    .afmfonts/afm/foundry/typefaceAdobe Font Metrics
    .tfmfonts/tfm/foundry/typefaceTEX Font Metrics for METAFONT and Type 1 fonts
    .vffonts/vf/foundry/typefaceTEX virtual fonts
    .pngtex/genericPNG images
    .jpgtex/genericJPG images
    otherstex/latex/packagenameother types of file unless instructed otherwise

    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.

    ‘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/username/texmf (on obsolete Windows systems you can use C:\texmf).

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

    Often there is just a .sty file to move but in the case of complex packages there may be more, and they belong in different locations. For example, new BIBTEX packages or font packages will typically have several subdirectories of files to install. This is why 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 folder 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, run your TEX indexer program after making changes

This step is essential, otherwise nothing will work.

Exercise 10: Install a package

Download and install the latest version of the enumitem package (which implements inline lists, among many other pieces of list formatting).

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 reason for having the local texmf directory (usually called texmf-local or texmf.local) is to provide a place for local modifications on a shared or managed system (such as a server) which will override but otherwise not interfere with the main TEX installation directory tree. 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 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.5.

3.2.3 Replicating the TDS

The TDS is documented at http://www.tug.org/tds/. I find it useful to make the subdirectory structure of your local texmf directory the same as that of the main installation texmf directory, so that I have all the main branches of the tree ready for future use. Examine the subdirectories of texmf/tex/latex/ for examples. For updates of packages which came with your LATEX distribution (as distinct from new ones you are adding yourself), you can then use the same subdirectory name and position in your local texmf/... as the original used in the main texmf/..., and LATEX will then always use the updated version.

If you want to create the entire subdirectory structure ready for use, you can do it under Unix & GNU/Linux systems (including Apple Macintosh OS X) with the commands below. This example uses the Ubuntu/Debian directory /usr/local/share/texmf rather than MacTEX’s /usr/local/texlive/yyyy/texmf-dist or Red Hat’s /usr/share/texmf-local in the cd command (replacing yyyy with the year of the MacTEX distribution, and using ~/Library/texmf/{} in the second command):

cd /usr/share/texmf 
find . -type d -exec mkdir -p ~/texmf/{} \;
        

Windows provides no way of doing this, although you could install Cygwin, which provides you with the standard Unix tools in a Command window.

  1. MiKTEX users MUST note that you cannot process .ins 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 the penultimate step ‘Install the files’, but there are a few remaining.