Skip to main content

Download and install JMRI®

JMRI Setup and Installation

JMRI environments...

Supported Hardware

Devices, command stations, networks, and protocols:

Release Notes

Source Code

Issues

JMRI Help:
Contents/ Index
Glossary/ FAQ

Donate to JMRI Donate to JMRI.org

JMRI Install Guide: macOS

Please note:

These directions are for installing the latest 4.x releases of JMRI® on current macOS computers.
If you have an older machine and need to install an earlier release (such as JMRI 3.10.1, 2.8, or even earlier), please see these MacOS X install instructions for older JMRI releases.

Now, on to the show:

Installing JMRI on your macOS computer

  1. Determine if your system software is compatible with the current releases of JMRI: Find the current macOS version number by choosing "About this Mac" from the Apple menu.

    2. JMRI 4.2 and later will work on any macOS or MacOS X version back to 10.7.3 Lion (2012). Note: MacOS X Lion 10.7.1 and 10.7.2 will have to be updated to 10.7.3.

    If your Mac hardware doesn't let you update MacOS X to a recent enough version, you can still use older versions of JMRI:

    • Mac OS X version 10.7.2 "Lion" through 10.6 "Snow Leopard" can run JMRI 3.10.1 using Java 1.7. (The youngest Mac that can't run Mountain Lion was shipped in 2009)
    • Mac OS X version 10.5 "Leopard" through 10.4 "Tiger" can run JMRI 2.14.1 using Java 1.6. (The youngest Mac that can't run Tiger was shipped in 2003)
    • For even older hardware, see a separate page.

    The JMRI install will take up about 180 MB of disk space, mostly for the Help pages and decoder definitions.

  2. Determine if you have the needed hardware drivers:

    No Macintosh that runs macOS 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 a direct USB connection, you will need macOS drivers (system software) for the hardware you're using. Most hardware won't need a separate driver; they're already present in macOS. In some cases you will need to install a special driver, though, so check the manufacturer's web site to make sure.

    Note: Mac OS X 10.11 El Capitan and later macOS versions generally require 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.

    For more instructions on USB connection debugging and testing for correct drivers, see the USB section further down on this page.

    We test using a Keyspan PDA Adapter; those drivers are available at http://www.keyspan.com/downloads/. 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".

    macOS drivers for FTDI chipsets are available at http://www.ftdichip.com/Drivers/VCP.htm.

    There's a macOS 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.

  3. Get the JMRI software...

    4. 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 JMRI users Groups.io group at https://groups.io/g/jmriusers.

  4. ...and install it.

    5. 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. We recommend you 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.

    Note that on macOS Catalina and later, you won't be able to run JMRI from within the Downloads, Desktop or Documents folder, so we strongly recommend you drag the JMRI folder to Applications and run it from there.

  5. 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 current macOS version, you can get the latest Java JRE installer as a free download at: java.com/download.
      After that download is complete, follow the included instructions to run the Java installer.
      More on Java versions and hardware requirements (prompts for Java in your browser).
      Older Java installations typically are removed by a MmcOS update. However, older Java applications are known to try and reinstall old stuff that might cause conflicts while running JMRI. See the instructions on how to check if this applies to your installation.
  6. Congratulations! Installation is complete. Click on the DecoderPro icon in the JMRI folder to get started.

Updating JMRI

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

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

Clean Install

If for any reason you wish to start totally clean and discard all previously stored Connections, Roster entries and Panels, delete the JMRI settings folder before starting the program. You will find it by choosing "Go to Folder..." from the Finder's Go menu (or ⌘+Shift+G). In the pane that appears, enter "~/Library/Preferences/", click "Go". If a "JMRI" folder is present in Preferences, move it to the Trash.

Starting JMRI

Connect your computer 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. More on this on the JMRI Setup help page. Go there next to complete your setup.

Mac OS uses names like "cu.SomeName" and "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 "cu." if both cu. and tty. are 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.

Debugging

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

USB Serial Issues

Irrespective of DCC system, there are some basic rules for troubleshooting any USB-attached device to a Mac.

Java SE 6

To check for Java SE 6, JMRI 4.5.2 and up include a script. Follow these steps (assuming JMRI is installed in the folder /Applications/JMRI; if it's installed in a different location, adjust the paths as needed):

  1. Open Terminal.app.

    El Capitan and later: Reboot into Recovery Mode by restarting your Mac and pressing Cmd-R until the Apple logo appears. Once in Recovery Mode, select Terminal from the Utilities menu.

  2. Run the command /Applications/JMRI/PanelPro.app/Contents/Resources/uninstall-java6.sh It can take up to a half hour to complete. Wait for the message Removed Apple Java SE6.

    El Capitan and later: Run the command bash /Volumes/Macintosh\ HD/Applications/JMRI/PanelPro.app/Contents/Resources/uninstall-java6.sh /Volumes/Macintosh\ HD It can take up to a half hour to complete. Wait for the message Removed Apple Java SE6.

  3. El Capitan and later: Restart your Mac.

Source: JMRI 4.5.2 Release notes.

Vector3f issue

Sometimes very old Macs have an older "vecsub.jar" library installed in a place that will cause problems for JMRI. It happens more often when you're compiling your own version, but it can also happen when just running a download. If you get messages about 

error: cannot find symbol getX()
or getY() or getZ(), the solution is to copy the JMRI/lib/vecmath-1.5.2.jar file from within the JMRI distribution directory to the ~/Library/Java/Extensions/ directory. (You might have to create that directory) Do not do this unless you have seen that symptom.

Notes

macOS 10.15 Catalina

Starting in early Fall 2019, macOS 10.15 Catalina greatly increased the security checks that macOS applications must pass before running.

Some issues:

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 macOS, 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".

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:

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.