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.org

JMRI Install Guide: macOS

Please note:

These directions are for installing the latest 4.99 and 5.0 releases of JMRI® on current macOS computers.
If you want to install a JMRI series 4 release, such as 4.24, please see the MacOS X install instructions for JMRI series 4 releases. 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.

    JMRI 4.99 and later will work on any macOS or MacOS X version back to 10.11 El Capitan (2015). (The youngest Mac that can't run Mac OS X 10.11 was shipped in 2011)

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

    • Mac OS X version 10.10 "Yosemite" through 10.7.3 "Lion" can run JMRI 4.24 using Java 1.8. (The youngest Mac that can't run Yosemite was shipped in 2010)
    • 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 360 MB of disk space, mostly for the Help pages and decoder definitions.

  2. Determine if you have the needed hardware:

    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 website to make sure.

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

    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, when configuring the connection in JMRI you should select the one that starts with "cu", e.g. "/dev/cu.KeyUSA19181.1".

  3. Get the JMRI software...

    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.

    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.

    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. If you want to keep it somewhere else, just drag the folder to the desired location. Note that if you it somewhere else, you might have to adjust permissions in the "Security & Privacy" pane of the System Preferences.

  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 DecoderPro OK, you have Java installed; you're installation is done! Quit DecoderPro, then go to the section on starting JMRI for next steps.
    • If that doesn't work, and you have a suitable macOS version (see above), your next step is to install Java 11. To do that, click on this download link. A download should start shortly. When it's complete, click on the file and follow instructions to install Java. (That link is the same as the download link near the bottom of this page on the Azul website.)
    • Note: JMRI 5 requires Java 11. JMRI 4 and 5 should work fine with some later versions (java 12 through 13) but you may get a message about "WARNING: An illegal reflective access operation has occurred" and "WARNING: Please consider reporting this to the maintainers". We know about this, and it'll get fixed in due course; you can ignore the messages. Java 14 and later will (currently) cause problems, so please use install and use Java 11.
  6. Congratulations! Installation is complete. Go to the section on starting JMRI for next steps.

A Note on Apple Silicon Macs

Apple Silicon macs, which use the M1 chip, can run JMRI in two ways:

  1. In native mode:
    You do this by downloading and using an Apple Silicon native-mode Java installation. This runs a little faster, though that doesn't matter much for JMRI. It has limitations, at least currently:
    • There's no native support for the HIDinput library that's used by some user's scripts to handle mouse and keyboard input.
    • There's no native support for the BlueCove library that's used to make direct LocoNet connections via the BlueCove BlueTooth adapter.
    • Before JMRI 5.3.7, there was no native support for the libraries needed for advanced sound features. This is fixed in JMRI 5.3.7 and later.
    If you encounter a problem in native mode, you can use the next mode.
  2. In emulation mode:
    You do this by downloading and using an Intel version of Java. (The Java download link above is to an Intel version.) This uses the Apple Rosetta system for translation and running, which is a slightly slower, but that's not likely to have much visible effect.

A Note on macOS Lockdown Mode

Recent versions of macOS have a "lockdown mode" which greatly increases security. Unfortunately, JMRI requires access to resources that are not available to programs when using lockdown mode such as USB hardware access, network access, etc. This means that JMRI won't properly start and run if your Mac has been set to lockdown mode. There's nothing we can do about this incompatibility: You can't both enable lockdown mode and run JMRI on the same machine.

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 if you kept them in the recommended places.

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.

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.