JMRI Install Guide: Mac OS X

These directions are for installing the latest releases (3.x) of JMRI.

If you need to install an earlier release (such as 2.8, or perhaps even earlier), please see these instructions for old JMRI releases. If you have a PowerPC Mac that can't run current Java versions, Marcus Horn has written up a possible migration path for you.

Now, on to the show:

Installing JMRI on to your Mac OS X computer

  1. Determine if your system software is up to date
  2. Mac OX X version 10.5.8 "Leopard" can run the current test and production releases. If you have 10.5 or later, just go to the next step.

    Mac OS X version 10.4 "Tiger" through 10.5.7 can only run JMRI 2.14.1, because that's the last JMRI version that can run on Java 1.5, which is the most recent Java version that's available on those Mac OS X versions. If you have "Tiger", you can download and install JMRI 2.14.1 via its release note.

    If you're still running Mac OS X 10.3 "Panther", you can download and use JMRI version 2.2.

    The install will take up about 120MB of disk space, mostly for the help pages.

  3. Determine if you have the needed hardware support.

    No Macintosh that runs Mac OS X has built-in serial ports, so if your layout hardware needs a serial connection, you'll have to use a USB to serial adapter.

    No matter if you have a USB to serial adapter, or a device with USB directly, you will need Mac OS X drivers for the hardware you're using. Most hardware won't need a separate driver; they're already present in Mac OS X. In some cases you will need a driver, though, so check the manufacturer's web site to make sure.

    We test using a Keyspan PDA Adapter; those drivers are available at Some device drivers will list each port under several names, e.g. starting with "/dev/tty" or "/dev/cu", for example "/dev/tty.KeyUSA19181.1". In that case, you must select the one that starts with "cu", e.g. "/dev/cu.KeyUSA19181.1".

    There's a Mac OS X driver for USB-serial adapters based on the Prolific PL2303 chipset available here. If you can't access your USB dongle and it seems to use that chipset (you can check in the USB tab of System Profiler), this driver will make it available as /dev/cu.PL2303-xxx.

    Note that because of baud rate limitations in Mac OS X itself, it is not possible to use a Digitrax MS100 currently. Use a RR-CirKits LocoBuffer-USB or Digitrax PR3 instead. Please see our page on USB adapters for more information.

  4. Remove any old serial communications libraries
  5. If you are installing JMRI for the first time, please skip to the next numbered step.

    Versions of JMRI before 2.9.2 required that you install communications libraries on your computer. If you had JMRI 2.9.2 or earlier installed and are now updating to a more recent version for the first time, you need to remove the communications library files that were installed earlier. You only need to do this once. To do this, follow the instructions on this separate page, then return here to complete your JMRI installation.

  6. Get the JMRI software...
  7. Download a version of JMRI, either the latest production version, or a "test version". Since the version numbers change with every release, this link takes you to the general JMRI download page, where you can select whichever version you like.

    The JMRI project is continuously adding features, bug fixes, examples and tutorials to the release, and so a new "test" version appears every month or so. You may find one of these has features that you really want. These are announced in the "jmriusers" Yahoo discussion group at

  8. ...and install it.
  9. Normally, the download will open a new window showing a JMRI folder. If not, double-click the file you downloaded above. This will open a window with the "JMRI" folder.

    To install, you just have to move the JMRI folder to where you want it on your computer. Many people put it in "Applications", which is the standard location for this. To do that, just drag the JMRI folder onto the "Applications" icon. If you want to keep it somewhere else, just drag the folder to the desired location.

  10. Congratulations! Installation is complete.

Configuring your JMRI setup

Connect your computer system to your command station hardware.

You can run the program by double-clicking on the "DecoderPro" or "PanelPro" or other application icons in the JMRI folder.

Depending on your security settings, when you first try to run a new JMRI version (usually by double clicking on the icon for DecoderPro or PanelPro), you may get a warning dialog that it "can't be opened because it's from an unidentified developer". In that case, dismiss the dialog, then hold the Control key down and click the icon to get its contextual menu. Select the "Open" option. You'll be asked to confirm. Be sure to click the "Open" button, and not accept the default "Cancel".

Your next step will be to set the preferences for your particular layout connection.

Mac OS X uses names like "/dev/cu.SomeName" and "/dev/tty.SomeName" for devices, including USB-attached devices like USB-serial converters, LocoBuffer-USBs and similar. Generally, you'll want to use the one that starts with "/dev/cu" if it's present, but see the specific installation page for your particular type of device. Sometimes you can recognize your interface from the right-hand part of the name. If not, the easiest way to find the name for your interface is to disconnect it, start JMRI, write down the list of available devices, close JMRI, reconnect the interface, start JMRI again, and look to see which extra name has appeared. That's the name one you want.

Problem Solving

JMRI supports many different Mac computers, with several different kinds of processors, multiple Mac OS X versions, and various layout hardware. Some combinations can cause trouble. This section gives some debugging hints.

Communications and Mac OS X 10.4

Mac OS X 10.4 was a transitional version, with lots of different structures in it depending on the subversion (10.4.1 vs 10.4.2 vs 10.4.3). Certain combinations of subversion and processor cause aren't properly handled by the standard libraries distributed with JMRI.

We handle this by making available some alternative libraries, at least one of which is going to make JMRI work.

If you've got Mac OS X 10.4 and are having a problem either getting JMRI to start, or seeing the attached layout hardware from within the program, please see this description of how to debug this.

Customizing Your JMRI Installation

You might want to have more than one configuration for DecoderPro or PanelPro preset. For example, you might to sometimes connect PanelPro to the command station on your layout, or other times have a configuration that doesn't use a layout connection so you can work with the program on a laptop away from the layout.

With Mac OS X, JMRI makes this easy to do. PanelPro and DecoderPro save their preferences separately, so they can be configured independently.

On a Mac, the different preferences files take their name from the name of the application icon that's invoked. This lets you create multiple copies of e.g. DecoderPro that each use their own, separate preferences files. Let's say you want one called "CoolNewOne".

  • Duplicate the DecoderPro application icon (ctrl-click to get a popup menu and say duplicate, or select the icon and choose duplicate from the File menu in Finder).
  • Change the duplicate's name. (It's probably better to use a simple one-word name like "CoolNewOne")
  • Double click your new icon, and off you go.
It won't work to drag one of the JMRI application icons out of the JMRI folder, since they need the other files that can be found there. If you want an icon in some other place, like on your desktop:
  • Go to the JMRI folder and select the application icon.
  • From the file menu, select "Make Alias"
  • Drag that new alias icon to it's new location, and optionally rename it.
Note that renaming the alias alone does not cause the application icon to be renamed, so the alias will be using the same preferences as the original.