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.

    Note: Mac OS X 10.11 El Capitan generally requires signed drivers. If you installed drivers for a previous version, particularly drivers that don't say they support Mac OS X 10.10 Yosemite, those older drivers may not work with 10.11 El Capitan. Go to the web site for your USB adapter, download the newest driver and install it before you update to El Capitan, or right after updating before trying to run JMRI.

    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. Get the JMRI software...
  5. 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

  6. ...and install it.
  7. Normally, the download will open a new Finder window showing a JMRI folder. If not, double-click the file you downloaded above. This should open a window with the "JMRI" folder. If that still doesn't open a window, look for a newly-mounted disk image (e.g. in Finder) and open that manually.

    To install, you just have to move the downloaded 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.

  8. Depending on how your Mac is set up, you might need to install Java.
    • Let's try the easy way first. Open the JMRI folder you just put in Applications, and double click on DecoderPro. If this starts up OK, you have Java installed. Move to the next step. If it opens a dialog box that offers to install Java, or takes you to the Java install web site, just follow those instructions.
    • If that doesn't work, and you have a recent MacOS X version, you can download the most-recent Java JRE installer from Oracle. After that download is complete, follow Oracles's instructions to run the installer.
    • If your Mac OS X version is so old that Oracle does not provide an installer, you can try to you can download an installer from Apple. In this case, you may not be able to run the most recent JMRI versions. Please go back to the top of the page for further information about older Mac OS X versions.
  9. Congratulations! Installation is complete.

Updating JMRI

If you already have JMRI installed and working, and want to update to a newer version, just:

  • Download the new version
  • Double-click on the downloaded file to open the disk image. That should open the contents in a new Finder window, but if not, open it.
  • Drag the new JMRI folder to the Applications icon to replace your existing version. If asked whether you want to do that, say OK.

Your existing configuration information, panel files, etc will continue to be used with the new version.

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 specific sub-version (10.4.1 vs 10.4.2 vs 10.4.3). Certain combinations of sub-version 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.