This page has been updated for JMRI 5 and Java 11. For the original version that includes information back to JMRI 2, see the original page. The original page also includes links to a number of special install instructions. Be aware that much of the information on these other pages is obsolete.
There are separate instructions for two custom Raspberry Pi images.
The following steps provide general instructions for installing JMRI on Linux using the terminal command line along with brief GUI descriptions for some activities. It should work for most Debian and Red Hat based distributions. It has been tested on Mint 20.3, Ubuntu 22.04, Debian 11, Raspberry Pi OS, CentOS 9, and Fedora 38. The serial connectons have been tested using the RR-CirKits LCC Buffer-USB.
Note: The instructions use the standard tilde (~) shortcut to represent the users's home directory at /home/<username>.
Starting with JMRI 5.0, Java 11 is required. See Install Java 11.
The majority of JMRI layout connections are based on serial ports. On recent hardware these are implemented using USB ports and a USB device such as the RR-CirKits LCC Buffer-USB. Most USB serial devices do not require the installation of drivers. The Linux user running JMRI needs to have read/write access to the serial ports. The following command updates the user's group list with access to the serial ports.
sudo usermod -a -G dialout ${USER}
Do not change ${USER}. That is a variable that contains the current user name.
The JMRI Linux install package is a tar gzip file, tgz. Click on Download. This will redirect the browser to the latest production download page. Click on the link for the Linux file. If a different version, such as a test release, is desired, use the links in the sidebar to select the release note for that version.
While at the download page, it is good idea to read the release note about the changes and any warnings.
The JMRI package is a complete JMRI implementation. There is no upgrade process. Any existing installs should be removed or renamed.
If custom components have been added to a JMRI install, they will need to be copied somewhere safe before removing an old version. To minimize the risk of losing custom components, they should be in the user files location. Profiles and other user data is in the ~/.jmri directory.
The recommended install location is the user's home directory. This reduces the possibility of OS or other application issues. The tar command is used to extract the JMRI directory.
tar xzf <file name> -C ~
Replace <file name> with the downloaded file name. The -C ~ writes the output to the home directory.
The tar command works on all Linux distributions. Most distributions also have a GUI tool to expand compressed tar files. This is accessed using the file manager right click context menu for the downloaded tar file.
Open With Archive Manager — When the archive opens, click on Extract. The next page is used to select the destination, such as Home. Then click on Extract.
Extract Here — Extracts JMRI to the current location. Move the extracted JMRI directory to the desired location. An alternate method is to move the downloaded file first and then do the Extract Here.
Open With Archive Manager — Same as Mint.
Extract Here — Extracts JMRI to the current location but within a new directory. Open the directory and move the extracted JMRI directory to the desired location.
Extract To... — After selecting a destination location such as Home, extracts JMRI within a new directory. Open the directory and move the extracted JMRI directory to the desired location.
Extract Here — Same as Ubuntu.
Extract To... — Same as Ubuntu.
Archiver — After the JMRI tar file is loaded, click on JMRI and then the Extract files icon. Select the destination such as Home and click on Open. Then click on Extract.
Extract Here — Same as Mint.
Extract To... — After selecting a destination location such as Home, click on Open. Then click on Extract.
Application icons are not required. PanelPro and DecoderPro can be started by clicking on
the scripts within the JMRI install in the file manager or from the command line. For example:
~/JMRI/PanelPro
As of the JMRI 5.3.6 test release, the CreateJmriApps.sh
shell script is included in Linux JMRI install. The script creates Linux application
definitions for DecoderPro and PanelPro. These are used by Linux application launchers such
as the LM popup in Mint, the Raspberry popup in Raspberry Pi OS, the application grids, etc.
These are stored in ~/.local/share/applications. The script will also create
desktop icons if the --desktop or the -d option is included
when running the script using the terminal command line, e.g.
~/JMRI/CreateJmriApps.sh --desktop.
For earlier versions of JMRI, the script can be downloaded from the JMRI Users Group at
CreateJmriApps.sh.
After downloading the script, move it to JMRI program directory and change the permissions
to make it executable: chmod +x ~/JMRI/CreateJmriApps.sh.
Use the following instructions if the script is not available, not suitable or a personal preference.
Use the Create a new launcher here... desktop action.
Note: The following technique also works for Mint.
Custom Linux applications,such as DecoderPro and PanelPro, are defined by a <name>.desktop file in ~/.local/share/applications. The files are used by the standard application launchers. These are normally a popup menu accessed by an icon such as the Mint LM or an application grid based launcher.
The definitions are data for the application launcher system so they do not need to be executable. Since they are in a hidden directory, enable the Show Hidden Files file manager preference.
Desktop icons are defined by the same <name>.desktop file, but are located in ~/Desktop. These files need to be executable.
Some distributions will also need Allow Launching enabled in the right click menu.
[Desktop Entry]
Type=Application
Encoding=UTF-8
Name=DecoderPro
Comment=JMRI Decoder Pro
Icon=/home/<username>/JMRI/resources/decoderpro.gif
Exec=/home/<username>/JMRI/DecoderPro
Terminal=false;
[Desktop Entry]
Type=Application
Encoding=UTF-8
Name=PanelPro
Comment=JMRI Panel Pro
Icon=/home/<username>/JMRI/resources/PanelPro.gif
Exec=/home/<username>/JMRI/PanelPro
Terminal=false;
Change <username> to the actual user name.
For distributions that use a "start menu" style popup menu, the JMRI applications will be in the Other group. The right click menu may have options. For example, Mint has an option to place the icon on the task bar panel.
For distributions that use an application grid, the application grid is displayed by clicking on the 3x3 application grid icon. The JMRI icon will show in the dock while the application is running and then go away when JMRI is stopped. The JMRI application icon can be added to the dock as a favorite by doing a right click on the JMRI icon in the application grid and selecting Add to Favorites.
The icon setup only needs to be done on the first install. The icons will continue to work when the JMRI install directory is replaced by a new download and extract.
The JMRI user data is located at ~/.jmri. This is a hidden directory. Some
applications ignore hidden directories. The Linux file manager normally has an option to make
the hidden directories visible. A symbolic link can be used to provide a substitute reference.
At the home directory, enter ln -s .jmri jmri in a terminal window.
The JMRI project is continuously adding features, bug fixes, examples and tutorials to the release, and so new "test" versions appear about once a month. These are announced in the "JMRI users" Groups.io discussion group at https://groups.io/g/jmriusers.
Additional information can be found at the "JMRI Linux FAQ page".