Search:   Help



LyX documentation


Shared groups


Mac /


Categories: Mac
<< | Page list | >>

Installing LyX on the Mac

This is an introduction to beginners. If your experience of installing programs is limited and your experience of using word processors is confined to using Word, this is the place for you.

1.  Why would you like to install LyX

If you want to create good looking documents on your Mac, you basically have three options:

  1. Learn typography and buy a DTP-program such as Quark or InDesign.
  2. Install LyX.
  3. Give up the idea of having good looking documents and use Word.

LyX is a front end to TeX, which is a computer implementation of the rules typesetters have been working by for centuries. By using LyX you can be sure that your documents look good.

So what do you sacrifice? Well, think about it as leaving your manuscripts to type-setting. Typesetters know what they are doing, but tend to have strong opinions. So if you want to have complete control on the layout you are in for trouble...

If that does not scare you off, continue for a guide on how to install and run LyX on the Mac.

2.  What you need

All software is completely free. But you will need:

  • A Mac with OSX 10.3.9 or higher (this demonstration was made with 10.4.4 and 10.4.5)
  • About 300 MB of free hard disk space (the installation is big, but the files you create will typically be small.)
  • Broadband
  • Administrative rights to the account (if you are the only user of the account you most likely have that)

I will try to keep this introduction short and to the point. If you would like the details on how to install LyX on the Mac, see

The installation might take anywhere between half an hour and half a day depending on your bandwidth and server load. But don't worry, it won't lock up your computer during the time and you don't have to babysit the computer during the installation.

3.  Installing TeX

Note: What follows is a description of a multi-step installation; if you want to install TeX in one go, use MacTeX. MacTeX is recommended for beginners and those pressed for time.

Let's dive right in. An explanation to what you have done is given in the end. You can read this explanation as your installation is progressing.

  • Download i-Installer [] (about 3MB)
  • Unpack by double-click (unless automatically done)
  • Open the Applications folder and then the Utilities folder and drop i-Installer there (technically you can place it anywhere you like, but if you place it here you will know where it is...)
  • Open i-Installer
  • Click Dismiss on the splash-screen
  • Choose i-Package -> Known Packages i-Directory...
Known Packages
  • Install the packages in the order outlined at: (see also below) by selecting them from the list and clicking "Open iPackage" and "Install" (or "Install & Configure")
    • You will be prompted for your password.
    • After each package has been installed, close the window (i-Package->Close)
Select Freetype
  • Time for installations on my machine (which has 100 Mb ethernet connection) and comments:
    • FreeType 2 -- 20 seconds
    • libwmf -- 20 sec
    • PNG Library -- 10 sec
    • Ghostscript 8 -- 1 min
      • Add /usr/local/bin to CLI environment: choose "Yes"
    • ImageMagick -- 1.5 min
    • GNU gettext -- 1 min
    • FontForge -- 20 sec
    • Fondu Mac Font cli Tools -- 10 sec
    • gwTeX based on TeX Live -- 15 minutes
      • Install type -- choose Basic
      • Which version? -- Choose the preselected
      • Type your password when prompted. Then there's a huge download, but you can keep track on the progress bar and in the status messages, which give the predicted time when each sub-package is downloaded. Take a coffee break...
      • Type your password again when requested and take another coffee break
      • Select the Paper size you like. Take a third coffee break.
Select Paper size

3.1  What have I done?

If you like to see what has happened, select the Finder and choose Go-> Go to Folder... (or press Cmd+Shift+G where Cmd is the Apple key). Type /usr and press return. Select local and then gwTeX. This is a directory that contains roughly 235 MB, which has been installed by the i-Installer. Normally you are not supposed to mess with this directory (but there are exceptions as we will come to).

teTeX Information

3.2  What do all these Megabytes contain?

They contain instructions on how to typeset documents. The additional packages you installed contain instructions for tasks related to this, such as converting image files to a format that can be used by gwTeX.

Now you can use gwTeX to create documents straight away, but unless you feel like writing input files like:


\title{Cartesian closed categories and the price of eggs}

\author{Jane Doe}

\date{September 1994}



   Hello world!


and typing some commands in the Terminal to get the corresponding pdf-document, LyX is your choice.

We will come to how you install LyX shortly, Let's just conclude by saying that you have installed a package that LyX will need to help you create nice-looking documents. How it works is something you actually don't have to worry about, although I can promise you that you will probably want to tweak the inside sooner or later. But that's another story.

4.  Installing LyX

Now it's time for the easy part: installing LyX.

  • Go to and install the latest version of LyX (this introduction was made using LyX1.4pre5).
  • Unpack and mount the disk image (by double clicking) if this is not done automatically.
LyX Installer Package
  • Print or save the pdf-files. In particular "mac-bind.pdf" is useful since it contains keyboard shortcuts that will speed up your work considerably once you get used to LyX.
  • Follow the instructions, i.e. drag the application to the Applications folder.
  • Run the install script by double-clicking. Select "Install". Provide your password when prompted (you need administrator rights).
    • Note that you have to run the install script for every account that uses LyX. The easiest way to do this is probably to run the install-script in the first account (as described above), move the install-script file it to the /Users/Shared folder (click your Disk icon, then Users, then Shared). Log in as the second user and then run the installation script from the /Users/Shared folder from that account (open the folder /Users/Shared and double-click the install-script).

Now you are done with the installation of LyX!

Installation Complete

4.1  What have I done?

The install script has created a directory "LyX-1.4" in the directory "Application Support" which is in the directory "Library" in your home directory. In that folder the script has placed some templates and other stuff. It has also put some templates in /usr/local/gwTeX/share/texmf.local/tex/latex/lyx/ which is deep down into the directory that was created by the i-Installer for the TeX-installation.

4.2  Why do we need two templates?

The easy answer is that the templates in the "Application Support" folder control what you will see on the screen when running LyX. The templates installed deep in the gwTex folder controls what you will see on paper when you print your document.

5.  Creating your first LyX document

  • Double-click your LyX icon (which should be in the Applications folder if you have followed the instructions above) and you will be greeted by a nice splash screen.
LyX Splash Screen
  • Select File->New
New Document
  • Type in the title of your text.
  • Now you have to tell LyX that what you have written is a Title. Select Title from the top-left pop-up menu. This will change the appearance of the text.
  • Press return, type your name and select Author from the pop-up menu.
  • Press return, type Introduction and select "Section*"
  • Write some sentences.
  • You should now have something similar to the figure below. Note the "--" in the title. This is used to tell LyX that it should produce a long dash (an n-dash, i.e. what you normally get when pressing alt+-). Now why not using alt+-? Because if you want an even longer dash (em-dash), you just type three dashes ---! The long dash does not show on screen, but it will show in print. LyX is full of such nice features (although some may be hard to discover at a first glance).

As you saw above, LyX works in the way that you tell the program: this is a title, this is the name of the author, and so on. Section* means that this is the header for a section, but that it should not be numbered (try "Section" without the star instead and you get a numbered heading).

Now the text you have written doesn't look fancy at all. LyX uses a bare-bone approach and just shows you what you really need to see. Let's look at what will appear on paper:

  • Choose View->PDF (pdflatex). After some thinking (the first preview is often slow), a pdf-document will appear in Preview:
Bad PDF Output

Now this actually looks like crap. The reason is that the fonts used are bit-mapped, which doesn't come out good on-screen (much better on paper). We need to do something about this:

  • In LyX select Documents-> Settings...
Document Settings
  • In the column to the left select Text Layout. Then set Font to "ae". This is a vector-based font that will look much better in preview.
Text Settings
  • Choose View -> PDF (pdflatex) again and notice the difference.
Good PDF Output

Now there are a bunch of other settings you can alter, such as document class (try for instance article (koma-script)), margins, etc. But this introduction will not delve in details on formatting. Those you can find at Instead we will look closer at some more Mac-specific aspects.

6.  Spell-checking

LyX is prepared for spell-checking and there are possibilities to obtain direct spell-checking within LyX. This is not especially hard, but it includes compiling a program (if you don't know what that means, don't worry).

If your use of LyX is confined to everyday tasks like writing letters, reports, etc. you can take an easier road:

6.1  A simplistic approach to spell-checking and cutting & pasting

If you don't feel an urge to install an integrated spell-checker you can instead use the spell-checker provided by MacOSX in the following manner:

  1. Select the text of the document by typing Cmd+a (That's the Apple key and an "a") or by clicking and dragging the part of the document you wish to spellcheck
  2. Copy the text by Cmd+c (or using Edit -> Copy)
  3. Open TextEdit (or any other program with spell-checking, e.g. Word)
  4. Paste the text there (with Cmd+v)
  5. Make your spell-checking in that program

As you can see, the standard Mac shortcuts work just fine in LyX. However, note that when you paste in TextEdit the formatting is gone. The reason is quite simple. We have never specified that the title should be in a larger font. All we have said is that it is a Title. TextEdit on the other hand looks for formatting of the text (bold, larger font, etc.). When it does not find any formatting, it simply pastes it as plain text.

Text pasted in TextEdit

What happens if we go the other way around?

Write some new text in TextEdit. Select it and copy it with Edit-> Copy (or Cmd+c).

Paste in LyX

Switch to LyX, position the cursor at the bottom and press return to get a new line. Then paste using Edit-> Paste (or Cmd+v).

Paste in LyX

That does not look right... What happened?

The text that was originally copied from LyX got pasted. The reason is that LyX uses two clipboard. You pasted the text from LyX "internal" clipboard. If you want to paste the text from another application you have to take another approach:

  • First delete the text you pasted (select by click-drag and press backspace)
  • Then re-position the cursor at the end of the document and press return to insert a new line
  • Now choose Edit-> Paste External Selection -> Selection as Paragraph (or Cmd+Shift+v)
Paste external in LyX
Paste external results

This results in almost the expected result with two notable exceptions:

  1. The boldface is lost. This is similar to the formatting loss when pasting in TextEdit.
  2. The line break is lost. This is actually a bug in versions prior to 1.4.1, but the screenshot hasn't been updated.

Due to the loss of formatting it is a good idea to spell-check in TextEdit and paste the corrected words into LyX (i.e. not pasting all of the text).

6.2  Advanced approach

Install aspell as described on the aspell Installation Instructions page.

This requires:

  • That you use the Terminal. Can be scary at first, but you will get used to it. See below for a gentle introduction.
  • That you have a compiler installed. If you don't know if this is the case (or don't know what a compiler is), the chances are high that you don't have a compiler installed. Then you will need to install the developer toolkit provided on the MacOSX installation disks (which is very easy, but requires a lot of disk space and is beyond the scope of this introduction).

7.  Installing templates

Now that you are experienced it is time to get advanced.

Let's say you want to write a paper for an Elsevier journal.

  • Start LyX
  • Select File->New from Template.

If the dialogue does not automatically position itself in the correct position, select your home folder. Then click Library (note that this is Library in your home folder and not under the hard disk), Application Support, LyX-1.4, templates and default. There you have a file called elsart.lyx.


This is a template for an Elsevier paper. Select it and press open.

This will cause Lyx to produce an error claiming that there is a "missing TeX-class".


What does this mean?

Recall that LyX acts as a interface for TeX. What the error message says is only that "OK, you have the file that tells LyX which layout to use (for instance how a title should be formatted on-screen), but you don't have the file that tells TeX how to format the output (how the title should look in print)."

You can check this by pressing OK. The file will open just fine and you can edit it and save the edited file. However, if you click the View menu, there is no option to show the pdf-file.

So I guess we need to find the missing file!

Open up Safari (or the web browser of your choice) and head for Search for "Information for authors" and "LaTex file guidelines" (if you can't find it, do a search for elsart.cls), and you will find a statement that "Users of LaTeX 2e need only one file: the class file elsart.cls."

OK, that sounds promising. Download the file by holding down Ctrl, clicking in the link and choosing "Download linked file".

Now comes the tricky part:

In the Finder make sure you have two windows open (if you have only one, open an additional using File-> New Finder Window)

  • In one window, select your hard disk's symbol and choose Go->Go to folder...
  • type usr
  • navigate to /usr/local/gwTeX/texmf.local/tex
    • (On my system that directory didn't exist, but putting the files into ~/Library/texmf/tex/latex/lyx worked)
  • In the second window select the file elsart.cls that you downloaded
  • Drag the file elsart.cls to the tex-folder in the first window
Copy elsart.cls

You will get an alert message. Click "Authenticate" and type in your pasword (you will need to have administrative rights).

Copy alert

OK, now we have found the file and placed it where it should be. But there are some few more steps needed. For these we need the Terminal (don't worry, we will fix this together and your computer won't explode).

  • open the Terminal-application (it is probably either in your Applications folder or in your Applications->Utilities folder).
  • write sudo texhash
  • type your password (again you will need to have administrative rights).

Some cryptic text will follow as seen below. Don't worry about that.

Terminal output
  • choose Terminal-> Quit Terminal

Now go to LyX

  • select Tools-> Reconfigure
  • a message will tell you that the system has been reconfigured and LyX needs to be restarted.
LyX reconfigure message

Let's do this:

  • select LyX-> Quit. Now LyX will ask you whether you wish to save any modified files. If not, click Discard.
  • open LyX again

Now open the elsart.lyx template file again (go throguh the procedure above starting with Select File->New from Template). This time there won't be an error message!

7.1  What have I done?

You have simply downloaded the description that TeX needs to produce the output and placed it in a folder where TeX will find it.

The "sudo texhash" commands simply tells TeX "Have a look on all the files in your folders and note all new templates" (remember the TeX-installation is about 300 MB, it would be quite time-consuming to look in all of these files for templates anytime a template is needed). The sudo-part is a way to tell the system that you are trusted to do this (remember we are messing with files deep down in the guts of the system).

The "Reconfigure" in LyX does the same for LyX, i.e. checks which templates that are available (it actually does a bit more, but that's nothing to worry about right now).

In conclusion, everytime you change something in the LyX or TeX configuration, you need to tell TeX and LyX about it.

8.  Updating LyX and TeX

Eventually there will be new versions of both LyX and TeX. Updating is simple.

8.1  LyX

Download the installer and follow the instructions (move the program file to the Applications-folder and run the installation-script).

8.2  TeX

Run the i-Installer (from Applications/Utilities if you followed the instructions above). Click Dismiss to close the splash screen.

Choose i-Package-> Open Updated Packages. If you have a relatively fast internet connection, choose Now.

i-Installer alert

i-Installer will now open all packages that have been updated. Click OK to close the dialogue that tells you that all packages have been checked.

Go through the packages and click Install (or Install & Configure) and continue as described for the installation above (except that you now also have to confirm that you wish to update in a dialogue by clicking Update). The downloads will be smaller during update since only updated portions will be downloaded.

9.  Final words

Now you have installed LyX, learnt some few basics with focus on the Mac-platform. Now you are ready to continue with the help of the massive amount of tutorials and manuals that are freely available on-line, see the LyX main wiki page

10.  Files

of the masterpiece created in this walk-through ;-)

11.  Contributors

  • Anders Ekberg


Edit - History - Print - Recent Changes - All Recent Changes - Search
Page last modified on 2010-07-23 11:55 UTC