TeX on Mac OS X

This is the R&A page on installing, configuring and running TeX on Mac OS X using i-Installer for the installation. It contains links to the current distribution and information that I think is useful for TeX users on Mac OS X. Other sources for TeX on Mac OS X info: A list of questions I have been asked in relation to my distribution is here. You won't believe it, but this whole installation lack of a train wreck actually attracts fan mail. An edited selection of that fan mail can be found here

i-Installer and my i-Packages are unsupported software as of Jan 1, 2007. For the foreseeable future I will be using i-Installer myself for several of my installs for personal use (mainly TeX) and as such I will maintain the program and some of my i-Packages.

What ends is e-mail support for people using i-Installer or any of my i-Packages. If you are looking for help, please join the Mac OS X TeX mailing list, which is the most active user community at the time I am writing this.

Bug reports can still be sent to me, but you will not get a reaction and it is uncertain if and when I will be paying attention to them. If it is something that does work for me (and thus something with your particular setup, I will most likely not pay any attention to them).

Using TeX on Mac OS X

TeX is a typesetting language. Instead of visually formatting your text, you type your text combined with commands in a plain text file. That file is your TeX source. You then use TeX to produce the final layout. Contrary to a normal word processor, the source and the output are basically separated in two different files.

TeX itself consists of a set of programs and a huge collection of support files containing macros for all kind of layouts (presentations, books, articles, special graphical tricks, etc). These macros make life easy for you. Instead of doing everything yourself in basic TeX commands, the macros provide an easy-to-use set of commands. For instance, the widest used macro collection is called LaTeX and you could type something like:

Macros? Commands? Typesetting? Cant't understand a word of the technical gibberish so far? DON'T PANIC! I think this page is not (yet) for you. Please go here first and then return and start again at "Using TeX on Mac OS X".

% comments start with the % character
\documentclass[11pt,a4paper]{article} % selects the article macro set and
% uses A4 paper size and 11pt font size
\usepackage[english,dutch]{babel} % use the babel multi-languages macros and
% select languages english and dutch (default)
\title{How to use \TeX} % defines the title. This macro is defined by the
% article class. The \TeX macro is defined in plain TeX
\begin{document} % starts the actual document
\maketitle % Produce the title. This macro is defined by the
% article class as well. The date is in dutch, our default
\section{How to use \TeX} % section header, defined by article class

\TeX\ is a typesetting language. Instead of visually formatting your text, you type
your text combined with commands in a plain text file.

You can use macro packages like \LaTeX.
TeX is a superb typesetter and is therefore very good at formulas: \[\Omega_0 = \left (
\frac{\alpha}{\beta} \right ) ^ 4\]


After running the TeX program on that source you will get something like this:

The above may seem complicated. But generally you have seen almost everything to make beautifully formatted documents. The rest is up to you: working in TeX frees you from thinking about visual layout almost completely. You can do what you should do: think about content. It is like having your own personal professional typesetter who worries about layout and does a very good job at it.

So, to use TeX you need basically 3 things:

TeX is able to produce PDF (Portable Document Format, a type of file that can be viewed and printed on most computer systems) directly from TeX sources. This is called pdfTeX.

TeX originally was only capable of producing the device independent DVI file format from the ASCII TeX source. To view or print DVI, the device independent data needs to be translated to a device. For instance an X11 or Windows user interface, or a PostScript or Laserjet printer. Sometimes, the users have to produce a printer format first (like PostScript), which then again is rendered on the screen by a PostScript viewer (like GhostView).

Mac OS X has a Unix core and it is therefore possible to use a Unix TeX distribution on Mac OS X. The source for TeX is TeX Live, the central TeX development system for Unix and other platforms (like Windows), which is published on CD once in a while. TeX Live is huge, programs (for a few platforms) and the foundation (macro's, fonts, etc.) together add up to 1 full DVD. The chief coordinator (there are quite a few maintainers of the various parts) of TeX Live is Sebastian Rahtz. A second very popular TeX (for Unix only) is teTeX, which has been created and is maintained by Thomas Esser. A big advantage of teTeX is that it comes with a well chosen set of support files: teTeX-texmf.

Apart from TeX (and GhostScript), the engine, you need a way to create the TeX source and view the output. If you are into basics and lack of comfort, you can use the existing TextEdit.app to edit your files, use the command line to run pdfTeX, and view the result with Preview.app or Acrobat. If you are less masochistically inclined, there are several frontends available that handle the edit-typeset-view phases for you. Some of them rely on the availability of a distribution like mine to do the work behind the scenes, other may be richer and pack their own TeX distribution. Here are a few frontends:

and tools that may be used when a TeX is installed: (links here are only added at the explicit request of the link owner, I do not maintain this list myself).

The gwTeX (re)distribution

My gwTeX (re)distribution is based on a subset of TeX Live with some additions/changes by myself. Most of it is a redistribution of work by others. I provide TeX-related i-Packages for i-Installer.app, which is a generic open source software installer. That i-Package will offer a somewhat friendly GUI interface to the basic TeX configuration aspects, like hyphenation patterns for languages, paper size, and so forth. I do keep a (Sep 2002, so rather outdated) volume available for emergencies: A dmg (Mac OS X mountable disk image file) with the original TeXGSInstaller.app can be retrieved by FTP from ftp.nluug.nl: TeX-old.dmg. That distribution will not be updated, contains only Ghostscript 6, and at some time in the future it will most likely disappear.

TeX i-Packages

The i-Installer application download can be found here: II2.dmg. This will download a disk image. A disk image is a file that contains an image of a disk. Such a file can be used just like a disk can. You need to mount that disk image. Mounting a disk image can be done by double clicking it in the Finder.

When the disk image has been mounted, you will have an extra `disk' listed in your Finder window. On it you will find two files, a README file and an Apple Installer.app .pkg. Install the .pkg on your system. i-Installer will be installed in /Applications/Utilities

Run i-Installer and (if you are connected to the internet) select the Known Packages submenu. You will be presented with a list of known packages.

The i-Installer volume is also mirrored. The following mirrors are available:

For TeX, you need the following i-Packages which you can open via the Known Packages window:

This will give you a working setup for pdfTeX and XeTeX, as well as for any TeX Frontend that uses the DVI format (normal TeX). Dvips is also included, so your setup will be able to generate PostScript. 
If you want to use TeX+dvips+ghostscript next to pdfTeX to produce PDF, you need If you want to use the type-1 (PostScript scalable) versions of the standard TeX Computer Modern fonts, you need to add to an existing TeX installation. Or you can use the Latin Modern set that is inside the main package. Or you install both and you can use both. Latin Modern is the preferred solution these days.
Seperate i-Packages are available for And there is a continually (daily) updated (if necessary) i-Package for ConTeXt: If you want to use graphic conversions from within TeX sources, you need to add: to an existing TeX installation.

You are hereby granted permission to mirror the TeX or i-Installer volume, under the following conditions:

TNH: TeX Know How

How and where do I report problems?

E-mail about i-Installer can be sent to ii2 at rna dot nl. Note that this address may be protected by an anti SPAM system, in which case you'll get a robot-reply to tell you how to reach me.

Please read the top of this page carefully. Bugs may be reported but I do not support this software anymore except for my personal use, hence, fixes may or may not come and may take a long time to come. If you report a bug, make sure to include.

i-Installer has a menu option Create & Display Report in the i-Package menu, which you should use preferably and if possible. This creates a report on settings, properties, output, etc. of you i-Package. If you select the menu item, a special tab view opens in the i-Package window. There you find a mail button to send it to me.

For support on TeX:

Get yourself on the Mac OS X TeX mailing list: Threaded list archives can be found at http://www.masda.vxu.se/~pku/MacOSX_TeX/. To subscribe, send email to info@email.esm.psu.edu with "subscribe macosx-tex" (without the quotes) in the body. For additional help, send email to info@email.esm.psu.edu with "help" (without the quotes) in the body.

i-Installer or i-Package Foo does not work on 10.2 and older!

Correct. Mac OS X 10.2 and older versions are not supported. Mac OS X 10.1 and older are not supported at all and no i-Installer version will run on them. For Mac OS X 10.2 you can download a volume of 357MB which contains a snapshot of i-Installer.app and all my i-Packages from Jan 24, 2006. All of these should install and work on Mac OS X 10.2. However, there have been so few users actually running 10.2 lately that this is not guaranteed.

Where can I get generic Mac OS X TeX help?

Not from me. I am not a TeXpert. Get yourself on the Mac OS X TeX mailing list. To subscribe, send email to info@email.esm.psu.edu with "subscribe macosx-tex" (without the quotes) in the body. For additional help, send email to info@email.esm.psu.edu with "help" (without the quotes) in the body.

Joseph Slater has put together a "getting started" page which might be helpful.

How do I set paper size in TeX?

Re-run the configuration stage of the TeX i-Package. You will be presented with various configuration options, amongst which setting the paper size.

Hey! Your distribution is broken!

Make sure that you have read my README's in /Library/teTeX (README.howtexfindsfiles and README.texmf.gwtex, these links only work when you are accessing them from a system where my distribution is installed and if the second one does not work your installation is outdated). Also, if you have installed personal material in ~/Library/texmf, move it out of the way and try again, before contacting me. Read the output from TeX to find out what could be the error. It is a lot of output, but generally it is rather easy to notice strange things like missing files, files loaded from weird (not /usr/local/teTeX) locations, etc.

Unavailable macros and packages!

I ship the binaries from TeX Live combined with the basic texmf tree (containing TeX macros and packages) from TeX Live (a subset of the full TeX Live) to which I have added a few packages that are not in TeX Live's distribution. What I ship is a mirror of what I am using myself, which has the advantage that broken things may get fixed before anyone runs into it but it has the disadvantage that errors introduced on my system get replicated. 

If a package is missing you can download and install it yourself, but you'll need to access the unix command line. Look for packages on Comprehensive TeX Archive Network, which also has a search engine. Or you can download and install the Full TeX Live and use that instead.

Help! TeX cannot find my file! / Where should I install any extra files?

It is possible to store additional style files, fonts, etc., in TeX itself. But TeX is owned by the system administrator and lives in /usr/local/gwTeX. It is a good idea to keep this directory pure so it can be upgraded easily when later versions are released. It is better to construct a mirror image of the teTeX directory structure inside your Library folder and store personal files there.

Here is how this works. TeX uses a directory structure invented by the TeX working group. Suppose you want to add a extra style file named new.sty to the style files used by Latex. Look inside TeX and notice that a natural spot for this file would be

So inside your home directory's Library folder, make a series of subdirectories as follows: and store "new.sty" inside this misc directory.

It is not necessary to replicate the directory nesting as deep as in this example. For .tex and .sty files and their like, using ~/Library/texmf/tex is normally enough depth. For font stuff, use ~/Library/texmf/fonts. Whatever you do below those levels is your choice and thus a matter of taste, it will not influence TeX's ability to find files. If you want to be certain however, copying the official structure is a good idea.

I use four (five) trees where files are stored:

  1. The first is /usr/local/gwTeX/texmf; this is where program-related stuff is stored and it is upgraded when the TeX programs are updated.
  2. The second is /usr/local/gwTeX/texmf.texlive; this is the main texmf tree based on a subset of TeX Live.
  3. The third tree is in /usr/local/gwTeX/texmf.gwtex and contains Mac OS X specific settings and additional packages not in TeX Live's foundation. This tree is maintained by me.
  4. The fourth tree is /usr/local/gwTeX/texmf.pkgs. This is where additional TeX support i-Packages (like CM-Super, MusixTeX) are installed. They will thus survive a main texmf tree reinstal and can be seperately updated, rmeoved, etc. The ConTeXt Updater also stores its stuff there. You can store your own additions as well here. To store in that area, you need System Administrator rights.
  5. The fifth tree is in /usr/local/gwTeX/texmf.local and is the place where local settings are maintained (e.g. languages, formats, maps).
  6. In addition, individual users can store their own files in ~/Library/texmf, as explained in an earlier paragraph.

When you reinstall the TeX i-Package, files in the first three trees are overwritten. But files in /usr/local/gwTeX//texmf.local and in user's home directories are normally left left alone (the exception being setup files created there by automated setup programs, which would break an upgrade if they remained in place).

TeX looks for files in the following order:

If you followed all this advice and it still fails, one unixy thing is: Open /Applications/Utilities/Terminal.app. In the window that appears type (note: case is important):

sudo texhash
you will be asked for a password. Give your own password. Note: this only works when you are logged in as a user with administrator rights (e.g. the first user that was created on the system).

A final word of warning: Mac OS X is a hybrid system between case sensitiveness and case preservation/insensitiveness. The combination might sometimes lead to weird results. The safest is to create all your directories and files exactly as they are written here.

For details, read the file README.howtexfindsfiles (this link only works when you are accessing them from a system where my distribution is installed). 

I am having configuration problems (with the command line tools).

A likely reason for this is a change in behaviour of TeX since 2004. TeX comes with a set of command line configuration tools, called updmap, texconfig and fmtutil (from teTeX). These tools had the following behaviour with respect to locations: they would read stuff in your personal directory (~/Library/texmf) if available, but they would always write in the system-wide settings directory (texmf.local).  Normally you would therefore have to call these tools as system administrator, hence a normal call would be something like:

sudo updmap --enable Map foo.map

And this is also what you will find in most instructions you see on the internet and in books. These instructions are wrong since the teTeX change. The reason is that Thomas Esser changed the behaviour and introduced special system-versions of his tools, called updmap-sys, texconfig-sys and fmtutil-sys. The non-sys versions will write in your personal tree, while the sys-versions write in the system-wide tree. When you use TeX, anything in your personal tree gets found before anything in the system-wide tree.

These days, the command above will give you unwanted results: adminstrator-owned files in your personal tree. The most recent TeX i-Packages deal with this situation by running utility-sys instead of utility, so you are creating a system-wide setting. In fact, what they do is run commands like 

sudo -H -u root updmap-sys --enable Map foo.map

Which makes sure the command is run as administrator and also on the basis of the administrator's personal texmf tree, which should not exist. So you get a pure system-wide configuration, ignoring whatever you have/any other user has in your/his/her personal texmf tree. 

If you do need a personal setup, different from other users (very few people actually do), you can use the non-sys utilities and you do not need to run them as administrator. E.g.:

updmap --enable Map foo.map

This will produce settings in your personal tree which are found first when you run TeX. Note that if you do this, you are on your own as nobody will be able to support everything people can think of. The Mac OS X TeX mailing list is your best bet for help.

Recent TeX i-Packages check for personal stuff during configuration and offer to remove it. If you don't, you run the risk that your TeX i-Package configuration phase works perfectly, but the results are never used because you override them with personal (possibly out of date) settings.

Why does ghostscript not display my .ps file?

Displaying files is not part of the standard GhostScript distributions. You need a special program for that.

However, most frontends will let you display PostScript files. They use ghostscript behind the scenes to distill PostScript into PDF, which is easily displayed on Mac OS X. Tom Kiffe's TeXTools (see above) contains an actual DVI-previewer (which means it can directly render DVI output, without making use of intermediate formats like PostScript or PDF). Given that in certain cases, direct DVI rendering gives the ultimate result, that tool may be handy for you.

How do I configure my installation to use the CM-Super fonts?

Install the CM-Super i-Package. Better is to use the Latin Modern fonts.

What environment variables do I need?

The simple answer is: None. Just install and use one of the GUIs, they will handle this for you. No unix fiddling required. Even the default command line will just work after an install and a restart of Terminal.app.

The more complex answer is: you need to add the binaries directory to your PATH environment variable to be able to use TeX. With respect to the command line, my i-Packages do that for the default Mac OS X shell. With respect to the GUI front ends, it is their responsibility to set the PATH before running a program. Some binaries will work when you call them with full path names and the PATH is not set, but most scripts will fail to work with an invalid PATH. Apart from PATH, I also add TeX to manpath.conf(ig). Note: when you update Mac OS X, these init files may be overwritten by Apple, in which case you need to re-run the configure stage.

If you get complaints about missing environment variables you probably have more than one TeX distribution on your system and they are in conflict.

How do I get a € symbol?

I use

in the preamble and then I can use \EUR in the text. Have a look at all the possible symbols in marvosym here.

What is this pdfTeX versus TeX thing?

Different output devices need different stuff to be able to create a display. For instance a 600 dots per inch printer needs a different piece of information to create a display then a 90 dots per inch screen. TeX normally produces DVI (device independent) output, which only contains information on the size of all the elements (like characters) and which fonts to use to combine these boxes-on-paper with character shapes from the font to make the final output. Another process is needed to create something readable. A DVI previewer can translate this directly to a screen, for instance. A program called dvilj4 can translate it to instructions for a HP printer.

The screen in Mac OS X is written using a language called PDF, a language which is also used for documents that can be printed. To be able to display TeX on a Mac screen you therefore need PDF output. There are two ways: