Download and install JMRI®
JMRI Setup and Installation
JMRI environments...
Supported Hardware
Devices, command stations, networks, and protocols:
Release Notes
Source Code

JMRI Help:

Contents Index
Glossary FAQ

Donate to

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.

  • A free Raspberry Pi image, completely configured with JMRI, auto-identify logic for many popular DCC systems and its own wifi access point, is available for download [here].
  • Pi-SPROG — See the SPROG DCC Ltd download page for up-to-date documentation.

JMRI Install Guide: Linux

General JMRI Linux Install Procedure

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

Install Java 11

Starting with JMRI 5.0, Java 11 is required. See Install Java 11.

Serial Port Access

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.

Download JMRI

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.

Install JMRI

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.

Raspberry Pi OS

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

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 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/ --desktop.

For earlier versions of JMRI, the script can be downloaded from the JMRI Users Group at After downloading the script, move it to JMRI program directory and change the permissions to make it executable: chmod +x ~/JMRI/

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.

  1. Right click on the desktop and select Create a new launcher here....
  2. Enter the icon name.
  3. Use the Browse button to select the PanelPro or DecoderPro script in the JMRI directory.
  4. The Comment is optional.
  5. Leave Launch in Terminal unchecked.
  6. Click on the icon.
  7. Use the Browse button to find the icon in JMRI/resources.
  8. After selecting the icon, click on the icon in pallet and click on Select.
  9. Click OK

Note: The following technique also works for Mint.

Define Applications

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

Desktop icons are defined by the same <name>.desktop file, but are located in ~/Desktop. These files need to be executable.

  1. Right click on the icon and select Properties.
  2. Select the Permissions tab.
  3. Enable Allow executing file as program
  4. Click on Close

Some distributions will also need Allow Launching enabled in the right click menu.

File Content
[Desktop Entry]
Comment=JMRI Decoder Pro
[Desktop Entry]
Comment=JMRI Panel Pro

Change <username> to the actual user name.

Application Options

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" discussion group at

Additional information can be found at the "JMRI Linux FAQ page".