This Install Guide is for JMRI versions 3 and later -
for earlier versions (2012 and before), refer to the old Windows Install Guide.
Using JMRI requires a combination of hardware (in this case running Windows), Java software and a JMRI download for a specific version.
JMRI® version 4.2 requires Java 1.8.
Version 3.10.1 requires Java 1.6 or later.
Version 2.14.1 requires Java 1.5 (or 1.6 if you wish for drag & drop).
Windows 7-10 and Vista SP2 can run the current JMRI test and production releases with Java 8.
If your computer runs one of these Windows versions, just go to the next step.
Computers running Vista SP1 can run JMRI 3.10.1 using Java 1.7.
Windows2000 SP3 and XP systems can run JMRI 2.14.1 using Java 1.6.
Windows98 and ME can run JMRI 2.8.
Note: It is possible to install Java 1.8 onto machines running Windows XP or Vista SP1, but this is unsupported by Oracle.
Donate to JMRI.orgjre-8u151-windows-i586.exe.
This is the last installer that worked for Windows XP; if you later get prompted to do a Java
Update to a newer version than 151, cancel it instead of applying it (if you do apply the update, you'll have to reinstall
the 151 version of Java as described here.)
The installer will complain that it is unsupported,
but should allow you to continue with the installation. Assuming that this is successful, proceed with
installation of current JMRI test and production releases.
It's important to have enough memory and free hard disk space. We recommend you have at least 256 MB of memory for Windows 98, 512 MB of memory for Windows 2000 and 2 GB for the newer W7-W10 systems. Note that used PC hardware is available for very little money; it might be cheaper to buy a used computer than to update your existing one.
Note: JMRI is developed with Java 1.8. It should work fine with later versions (java 1.9, Java 10, 11, etc) 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.
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. Get the file labeled "Windows" with a .exe extension.
JMRI also supports an offline installation - to setup, refer to the Offline Installation section below.
The JMRI project is continuously adding features, bug fixes, examples and tutorials to the release, and so new "test" versions appear every couple of weeks. You may find one of these has features that you really want. These are announced in the JMRI users Groups.io group.
When the JMRI download is ready, you will be asked to either save it to disk or directly run the installer.
It will then check to see if a previous version of JMRI exists, backup any Preference, Roster and other settings and, if necessary, uninstall the old JMRI version.
You may choose to have the installer make a backup of the existing files, and provide a location on disk for this set.
In some circumstances, the removal of version 2.5.1 or earlier is not successful:
Uninstaller failed
In such cases, it is necessary to download and run the following file and then re-run the installer:
RemoveOldJMRIUninstallEntry.exe
If supported by your Windows version and depending on the permissions of your user, the installer may ask you to choose to install JMRI just for yourself or for all users of the computer.
The installer will now present a list of the components to be installed.
This will install JMRI to the default location, place shortcuts for DecoderPro and PanelPro on the desktop and create a JMRI Start Menu folder containing shortcuts for typically used JMRI programs.
If you wish to change where JMRI is installed, change the install type from 'Typical' to 'Custom (select to choose program folder)' using the drop-down menu.
The next screen suggests a place for the install.
The following screens lets you choose a place for JMRI in your Start menu.
It will check for a suitable version of Java on your computer and, if required, will connect to the internet to download the most current version for your computer (for an offline installation, refer to the Offline installation notes below).
Downloading java
Once existence of a suitable Java Runtime Environment has been confirmed, it will then install the needed libraries, plus add a "JMRI" program group to your Start menu and put shortcuts to the DecoderPro and PanelPro programs on your desktop.
Click Next.
The Windows JMRI installer for version 2.5.2 or later supports an offline installation of Java and JMRI. Typically, this would be used when the computer on which you wish to run JMRI does not have internet access.
(The following instructions assume that you are setting up a blank removable flash drive - creation of a CD will be similar but may depend on the capabilities of your CD authoring software)
The following image shows the resulting structure:
Setup of the JMRI offline installation media is now complete.
If for any reason you wish to start totally clean and discard all previously stored Connections, Roster entries and Panels, run "Uninstall JMRI", found in the Windows Start Menu > All Programs > JMRI > Tools and Demos before reinstalling a new version of JMRI.
(This shows the Start menu following a 'Typical' install - a 'Full' install will place additional icons in this menu)
DecoderPro may encounter problems if the Serial Port used to connect to the layout shares an interrupt with another Serial Port. Typically COM1 and COM3 share an interrupt, as do COM2 and COM4. In particular, some systems are unable to communicate (and may experience a lockup) when the layout's Serial Port shares an interrupt with a port used for a serial mouse. Make sure that the Serial Port connected to your layout does not share an interrupt with another Serial Port.
With Windows XP, your Serial Port parameters might not be properly set for hardware flow control. To fix this, right-click on My Computer and select Properties. Go to the Hardware tab and click on Device Manager. Open up the section that says Ports (COM & LPT). Right-click on the Serial Port you have the LocoBuffer hooked up to and select Properties. Go to the Port Settings tab and set the options to:
19200, 8, None, 1, Hardware.
Click OK. Quit the application and restart JMRI. Verify your connection settings.
Depending on what it wants to display, JMRI can open up very large windows. Generally, JMRI uses the size of the screen and information about fixed things like the start bar to decide the maximum size for an opening window so that e.g. the corners can't be reached to resize the window.
Depending your Windows display operation, large JMRI windows will either resize to stay on the large part of the screen, clear of start bars and menu bars, or will be displayed at the full size of the screen, appearing under the start bar and menu bars.
This is controlled by the Taskbar and Start Menu Properties control panel. JMRI windows can open to the full screen size if the 'Keep the taskbar on top of other windows' option is de-selected.
Also, they can open to the full screen size if the 'Auto hide the taskbar' option is selected
If you're using a "skinning" utility which changes the appearance of programs running on your computer, you should tell it to ignore the "java.exe" program. That's how JMRI and DecoderPro will appear to it, and they weren't written with such "skins" in mind.
During installation, JMRI can do a number of things automatically that makes it easier to revert to a previous working setup if a major problem is encountered in a test release.
Note: This procedure will not preserve work done since upgrading; it restores everything back to the state at the time of upgrade.
A backup copy of all your user files (Panel files, Roster entries, Preferences etc.) is saved when a new revision of JMRI is installed. This is done by the installer when it asks to save a backup copy which, if selected, is saved in a folder named "JMRI_backup".
When installing a newer version of JMRI than that already installed, backup creation is defaulted to "Yes"; when installing an older version, it is defaulted to "No".
If problems occur with the new version and it is necessary to revert to the
last version in use, you should install the older version right over the version
currently installed. Then find the folder that holds the folder named "JMRI_backup".
This will normally be located in your user-profile folder - a quick way to
find this is to follow the "Preferences" link in "JMRI > Tools and Demos" from the Start menu.
Once opened, navigate up one level to your user-profile folder.
Depending on the version of Windows, this will typically be one of:
Restart JMRI and you should be back to where you were before installing the new version.
Sometimes things go wrong. The information in this section can help.
The JAVA SE Platform binary has stopped working
WARN - Could not open/create prefs root node Software\JavaSoft\Prefs at root 0x80000002. Windows RegCreateKeyEx(...) returned error code 5
With JMRI a utility called InstallTest.exe is installed. To execute a series of tests on your Windows JMRI installation, start InstallTest from the Start menu -> Programs -> JMRI -> Tools and Demos -> InstallTest. The following screen will open:
Press any key to continue (after reading the screen).
JMRI logs information about errors to a "messages.log" file in the "systemfiles" sub-directory of the JMRI preferences directory, and to a console window. This window is generally white text on a black background, and is labelled either "Java" or "DOS". If something is going wrong, look there for more information.
If you're asked for a copy of the error messages, you can usually get them from the messages.log file. If you can't find it there, make a copy of the log window:
To assist with resolving JMRI start-up issues, it is possible to modify the Start Menu shortcut used to launch JMRI.
Shortcuts are modified as follows:
When launched, the following window will appear showing various useful information:
Copy the contents of this window by 'right-clicking' and then choosing 'Copy Details to Clipboard'
For further information on the JMRI shortcuts, see the page outlining the start-up procedure on Windows.
To assist with resolving JMRI shutdown issues, it is possible to modify the start menu shortcut used to launch JMRI.
Shortcuts are modified as follows:
When launched, the Java System Console window will appear showing various
messages from the JMRI program:
For further information on the JMRI shortcuts, see the Help page outlining the start-up procedure on Windows.