• View
• Edit
• Upload
• History
• Print

LyX for Mac OS X

This is a HOWTO for LyX/Mac, a full-featured native implementation of LyX on the Mac OS X.

1.  Download

LyX/Mac is available as a binary for Mac OS X 10.4 and later. (Note additional prerequisites below.) The download page is here. There are currently two different binaries:

• LyX-XXXX+qt5-x86_64-arm64-cocoa.dmg - build on BigSur for Intel and Apple chips (minimum macOS 10.14 with Qt 5.15.7).
• LyX-XXXX+qt5-x86_64-cocoa.dmg - build on Mojave for Intel chips (minimum macOS 10.12 with Qt 5.12.9).

For users who prefer emacs-like modifier key bindings, there is additional information on customizing these keys, including patched binary versions.

2.  Python

LyX depends on a usable Python installation on your system. Until macOS 12.3 (Monterey) Apple shipped the OS with Python 2.7. With macOS 12.3 Python isn't part of the OS anymore. It's part of the tools for developers. So it needs to be installed manually to use LyX. This is true for latest macOS (Ventura) too.

If you run LyX the first time on a Mac with macOS 12.3 (Monterey) or newer and haven't installed Python yet you'll get two message boxes partially overlapping each other (see first image of Apple Python). The topmost is from LyX and it tells you the following:
LyX will only have minimal functionality because no text classes have been found. You can either try to reconfigure LyX normally, try to reconfigure without checking your LaTeX installation or continue.

The second message box is from Apple and asks for download and installing the Command Line Tools.
The "python3" command requires the command line developer tools. Would you like to install the tools now?

If you've just updated your macOS from a version before macOS 12.3 (Monterey) you may have no problem for some time. But the OS update removes the Python 2.7 utility and installs the stub Python 3 utility instead. The symptoms for the missing Python 2.7 utility are failures on image conversion, reconfigure of LyX or when opening LyX files from former LyX versions. E.g. the error message for the failure to convert an image after an update to macOS 12.3 (Monterey) or later looks like that:

There are three options to install Python:

1. Apples Python 3 - install the command line tools of Xcode
2. Original Python 3 - download and install the software package from python.org
3. Open source package manager - use Macports from macports.org or Homebrew from brew.sh

Option 1 is good for users with Apple software preference. It should be Apples responsibility to keep it up-to-date. Option 2 requires much less resources for download, install time and disk space. Option 3 is good for developers and users with affinity to use other open source software on the Mac (e.g. for advanced image processing task).

2.1  Software Download

The image shows the directory with LyX software disk images, the TeX distribution for typesetting and the original Python package.

To install LyX one open the disk image and copy the LyX application to the applications folder.

2.2  Apple Python

The first option is used automatically if there is no Python available via option 2 or option 3. The macOS installers for Monterey 12.3 and above provide a stub Python binary to ask for download and install the command line tools of Xcode in case the Python utility is requested. With the first start of LyX it creates the initial configuration files and triggers the question to install the command line tools of Xcode. The process to create the initial configuration files fails and LyX raises another message box to decide how to proceed.

To use Apple Python one has to start the download and wait for the successful install of the command line tools of Xcode. This is a bit time consuming but not as long as it is initially announced.

Until the installer has finished one should close the message box and quit LyX.

After successful install of the command line tools of Xcode there is a usable Python on your system. LyX is able to create the initial configuration files and ready to use.

2.3  Original Python

To use the original Python download the software from python.org and start the installer.

Finally LyX is able to use Python to create the initial configuration files and run the converters to assemble the document parts, including images etc.

3.  Gatekeeper

With Mac OS X Mountain Lion a new feature is active: the Gatekeeper. It's there to help protect your Mac from malware and misbehaving apps downloaded from the Internet. An app that is delivered by an unknown developer — one with no Developer ID — will be blocked. To get a developer ID one has to buy a license from Apple with yearly costs.

Since macOS Catalina the apps may be notarized by Apple to be sure they are free of malware. Because there is no support for open source programs like LyX by Apple the LyX package is not notarized and you have to be sure you got the package from our download page (in case you are GPG user we provide gpg signatures to verify the package check sum, see Download Checksums & signing section).

Having the Gatekeeper is a good thing and fortunately there is an easy way to start LyX without disabling Gatekeeper. Starting with macOS Sequoia (macOS 15.0) the procedure has been changed. At first the procedure for earlier releases is shown.

3.1  From Mac OS X Mountain Lion to macOS Sonoma

"LyX" can't be opened because it is from an unidentified developer.

1. Don't open the application with a double click. Click it while pressing the Control-key instead.

2. Choose Open

3. Another window is opened. There you choose open again. That's it.

More information is available here (the Apple documentation).

3.2  macOS Sequoia

The following pictures are made on a system running the german localization. The natural method to start the LyX application is to double-click on the icon. macOS doesn't start it but presents an alert. The alert that Apple cannot check the app for malicious software looks like this one.

1. Don't open the application with a double click. Click it while pressing the Control-key instead.

2. Choose Done instead of Move to Trash

3. Open System Settings, select Privacy & Security and click the Open Anyway button to confirm you want to enable LyX.

4. Open the LyX application with a click while pressing the Control-key again and confirm again you want to open LyX.

More information is available here (the Apple documentation).

Mac

4.  Prerequisite

You need a TeX installation. The easiest option is to use MacTeX. The .dmg file for a complete MacTeX installation is very large (> 1 GB), but it is a very complete distribution and installs right out of the box. MacTeX includes all the components necessary for TeX to work, and includes the bibliography managing program BibDesk.

Users with slower download speeds might want to download BasicTeX, a much smaller distribution, linked from the MacTeX page.

5.  Useful Helper Programs

5.1  Previewers

LyX/Mac uses the system default viewers, and should require no configuration for PDF and HTML.

5.2  Spellcheckers

As of LyX/Mac 2.0, spellchecking support is included by default.

5.3  Bibtex tools

• BibDesk is a highly recommended tool for maintaining BibTeX databases. Other possibilities include JabRef, tkbibtex (used with Tcl/Tk Aqua) or its aquafied counterpart, AquaTkbibtex, respectively, and Endnote (used with scripts that convert Endnote citations to LaTeX citations).

5.4  Envelopes

To print envelopes, install envelope in /usr/local/bin and make it executable. While you're writing a letter in LyX, do File -> Export -> Custom -> ASCII and give envelope as the command; it will parse the address from the letter and print an envelope, including the USPS barcode.

5.5  OmniGraffle converter

OmniGraffle is a great software for creating diagrams under Mac OS X (in particular, it works very well with LaTeXiT so that you can easily insert math formulae into diagrams). As it doesn't have a command line mode, you can use an AppleScript in order to insert ".graffle" files directly into LyX.

• Put og-export.scpt somewhere on your disk (e.g. in $HOME/Library/Scripts/).
• In order to use it, go to LyX preferences, add an OmniGraffle file format (just type auto for the editor), and then add converters:
  • OmniGraffle -> PDF (ps2pdf) converter: osascript replace/with/path/to/og-export.scpt `pwd`/$$i `pwd`/$$o pdf
  • OmniGraffle -> EPS converter: osascript replace/with/path/to/og-export.scpt `pwd`/$$i `pwd`/$$o eps
  • OmniGraffle -> PNG converter: osascript replace/with/path/to/og-export.scpt $$i $$o png
• Note that currently, LyX doesn't work with OmniGraffle packages (e.g. diagrams including images). This problem will hopefully be solved in the future (see this bug for details).

5.6  On screen quality of included PDF files

When you include a PDF graphic in a LyX file, it will appear crisp in the typeset PDF file of your document, but the version you see in the LyX window can be quite ugly. Lyx converts PDFs to PNG to show them in this window, and the default conversion method can choose quite a low definition for these bitmaps. A quicker and better solution would be to include a converter that uses the sips program that comes with OSX (it is a command line tool that you can use in the Terminal for converting a graphic file between different formats). To create this converter, you should open the Preference menu item in the LyX menu, and go to the File handling tab, then the Converters item. Here we will use the PDF (graphics) ->EPS item as a template. When you choose this item, the bottom boxes are filled and you can read a command that starts with pdftops... in the converter box. We will first change the EPS item on the right to PNG (you should have this possibility in the combo that opens when you click on EPS), and change the converter command as consequence, by replacing the complete psdtopdf... command by:

sips --resampleWidth 600 --setProperty format png $$i --out $$o

You can also increase the resampleWidth value if the generated bitmaps look too small on your screen (please first check that Lyx shows them at 100% of their size). When you finish setting these parameter, click Add button next to the top converters list (if not, you will loose the new converter), then click Save. If you open a new file containing PDF graphics, they should be much better looking and crispier now. If you want to change these values later, you should come to the same screen, select this converter, change the parameters in the converter box, and click Modify before leaving this screen.

6.  Beyond basics

6.1  PdfSync and SyncTeX -- Forward Search and Reverse Search

LyX allows, using a suitable viewer such as Skim.app, to navigate quickly between a particular place in a LyX document to the corresponding place in the rendered PDF document (forward search) and from a particular place in the PDF back to the corresponding place in the LyX document (reverse or inverse search). However, some set-up is needed before this functionality is available.

• Please note that there are more up-to-date instructions using SyncTeX on this wiki at http://wiki.lyx.org/LyX/SyncTeX where the free OS X PDF viewer Skim.app is used. (Skim is highly recommended for this use.)
• Please note also that there are new instructions about reverse search in Additional Features Manual.

PdfSync is similar to reverse DVI search but is for the (now more common) method of directly producing pdf files. If you use the program Skim as your previewer you can COMAND-SHIFT-click in the previewed pdf file which causes the cursor to move to that point in LyX.

• In LyX > Preferences > File Handling > File formats > PDF (pdflatex), in the Viewer setting select "Custom" and then enter open -a Skim.app $$i in the viewer setting. Then click Save.
• In Skim > Preferences > Sync select LyX.
• Include \usepackage{pdfsync} in the preamble of your LyX files.

  Troubleshooting PdfSync

  Make sure that the .lyxpipe.in and .lyxpipe.out files do not exist when LyX is not running. (They are normally deleted when LyX quits, but if LyX crashes, they remain and prevent LyX from communicating with PDFView.) Their location can be found in LyX > Preferences > Paths.

6.2  Version Control

• Please note that there are new instructions about version control in Additional Features Manual.

Version control is useful for managing large documents, or documents with multiple authors. In order to implement it, you need to have RCS (Revision Control System) installed. This is a standard part of Xcode. The simplest way to get version control working, is to install the Xcode Tools package contained on the OS X install DVD. See the Mac Version Control page for more information.

6.3  Interaction with X11.

Xfig or X-windows previewers like xdvi or gv can be used with LyX/Mac if you modify your ~/MacOSX/environment.plist file. For details, see the environment.plist page. Alternatively, you can change the viewer for postscript or dvi with DISPLAY=:0.0 gv or DISPLAY=:0.0 xdvi. Note that X11 must be running first for either of these to work.

6.4  DVI viewers

By default, LyX will generate PDF files. If for some reason you prefer to create and view DVI files, some set-up hints are provided on the Mac-DVI page.

7.  Pipes

7.1  Name in Path Problem (JabRef)

Programs such as JabRef communicate with LyX via pipes, which are sometimes named incorrectly by default (e.g., they assume that the pipe is in a directory that has a space in its name, such as Application Support, but other programs often cannot deal with spaces in paths). You may need to fix the lyxpipe path in both LyX and JabRef in Mac OS X.

To fix the LyX pipe in JabRef, open JabRef and go to Preferences>External Programs and in "Path to LyX pipe" enter /Applications/LyX.app/Contents/Resources/lyxpipe. Close JabRef.

Then open LyX, go to LyX>Preferences>Paths, and in "LyXServer pipe" enter /Applications/LyX.app/Contents/Resources/lyxpipe. Reconfigure. Close LyX.

The next time you run LyX and JabRef, you should be able to push citations directly from your BibTeX bibliography in JabRef into LyX. If anything goes wrong, JabRef will return an error message, and you will have to redefine the pipe. You might try the following: (1) change the LyXServer path in LyX -> Preferences -> Paths back to ~/.lyx; (2) recreate the ~/.lyx directory by entering in a terminal session, "mkdir ~/.lyx"; and (3) restart LyX.

8.  Key Binding on Sequoia

MacOS Sequoia appears to take the shift-command-M key binding for itself. This prevents it being used as a shortcut to enter a display maths formula.

The binding can be released by unticking "Open man Page in Terminal" in the MacOS Settings -> Keyboard -> Keyboard Shortcuts -> Services -> Text.

9.  Known issues

1. Due to limitations in the Qt/Mac library, interface languages other than English modify the organization of the toolbar menus and it may not be possible to directly enter some special characters into the document preamble (you can copy them to the preamble).

Please report any other bugs to the appropriate LyX mailing list. A web gateway is also available.

The information on this page is believed to be accurate, has been used successfully on many systems and sites, and has benefited from the comments and suggestions of many users. Due to the variations in individual systems, this information and the various files and code available on this page are conveyed as is with no warranty of any kind.

10.  More information

This group contains the following pages:

11.  Categories

Mac JabRef lyxpipe TeX