JMRI Install Guide: macOS
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
- 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.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.
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.
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.
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.
- 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:
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.
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.
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, start JMRI again, and look to see which extra name has appeared. That's the name one you want.
DebuggingJMRI 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 IssuesIrrespective of DCC system, there are some basic rules for troubleshooting any USB-attached device to a Mac.
- Plug your device into your Mac.
- Go to "System Information" from Apple Menu->About This Mac->More Info->System information.
- Look in the USB section, expand all sections under controllers and hubs and see what devices are present.
- Unplug your device, select Refresh from the System Information menus and see what device has disappeared. Plug your device back in, refresh again and see what reappears. Repeat until you see what is changing. If there is no change, there must be a hardware problem external to your Mac, such as a faulty USB cable, connector or device and there is no point going any further until your Mac can see the physical device.
- Once you have seen the device in System Information, (it should report the Manufacturer name so you know where to go to get drivers) you will quite likely have to install Mac drivers for it (although some do not need extra drivers, see your documentation). If unsure, try the next step anyway.
- In High Sierra and above, you must open System Preferences->Privacy and Security and allow the kernel extensions (drivers) you installed to be loaded, or they will not be used.
- Unplug your device. Open a window of the Terminal utility (from /Applications/Utilities),
copy and paste the following command in EXACTLY (including spaces and punctuation) then press Enter.
while : ;do clear;ls -lt /dev|head;i=$((i+1));echo $i;sleep 1;done
This command should show about 10 lines of output and then sit looping, with a counter incrementing every second.
- Plug your device back in and wait a few seconds. Two new items with names like cu.xxx and tty.xxx should appear in the list. They should disappear if you unplug your device. If this does not happen, you do not have the correct drivers installed for your device and you will need to solve that before proceeding further. Once you have found your device, write down the name you see. You want the cu.xxx version not the tty.xxx version.
- If you have got this far you know your device is be being seen by the Mac, that it has a matching driver installed and the name of the connection port "cu.xxx" you need to select in JMRI. If you cannot get this far, there's no way JMRI can find your device until the driver issue is resolved.
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):
- 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.
- Run the command
/Applications/JMRI/PanelPro.app/Contents/Resources/uninstall-java6.shIt 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\ HDIt can take up to a half hour to complete. Wait for the message Removed Apple Java SE6.
- El Capitan and later: Restart your Mac.
Source: JMRI 4.5.2 Release notes.
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
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.
error: cannot find symbol getX()
macOS 10.15 CatalinaStarting in early Fall 2019, macOS 10.15 Catalina greatly increased the security checks that macOS applications must pass before running.
- If you upgrade to Catalina on a computer with a working JMRI installation, it should continue to work. (If not, please let us know on the jmriusers group.)
- If you installed Oracle's Java 8 before upgrading to Catalina, it'll still work. If you want to install Java 8 from Oracle onto a Catalina system, there are some instructions on the Oracle web site. The Oracle Java 11 installer is an easier installation, and works fine with JMRI, so we recommend you do that instead.
- JMRI versions before 4.17.5 are very hard to properly install on Catalina, and we don't recommend trying.
- We hope to have JMRI 4.17.5 fully compatible with Catalina for new installs. To install JMRI 4.17.5 or later on Catalina, please drag the JMRI folder to the Applications folder. Depending on your system security settings, dragging it to Downloads, Documents or Desktop might not work.
Customizing your JMRI InstallationYou 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".
- 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.