Please note:
These directions are for installing current
5.x releases of JMRI® on current macOS computers.
If you want to install a JMRI 4.x release, such as
4.24,
please see the
macOS install instructions for JMRI 3-4 releases.
If you have an older machine and need to install an earlier release, please see our
Early MacOS X install instructions.
Now, on to the show:
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:
The JMRI install will take up about 360 MB of disk space, mostly for the Help pages and decoder definitions.
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".
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.
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.
Apple Silicon macs, which use the M1 chip, can run JMRI in two ways:
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.
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.
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.
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, restart JMRI and look which extra
name has appeared. That's the name one you want.
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.
while : ;do clear;ls -lt /dev|head;i=$((i+1));echo $i;sleep 1;done
Some issues:
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.