JMRI: Preferences Pane

The Preferences pane is where you configure the basic operation of your JMRI application.

The screen is split into two sections: on the left hand side is a list of the Preference groups that can be set. Clicking on each item will then populate the right hand side with the various options that can be configured for that Tab.

Perhaps the most important control is at the bottom of this section: The Save button!

Be sure to click Save before leaving this window. Your changes to the Preferences don't take effect until the program is stopped and restarted, so the program will prompt you to do that after saving the Preferences.


Some preferences take effect when changed but will later display a reminder prompt to save the changes before quitting.

Save? dialog


You can select any of the various JMRI layout Connections here.

JMRI v2.14 Connection Prefs tab Each connection has its own unique tab. To get started, first select your DCC System Manufacturer, followed by the type of Connection that you are using. You will then be presented with a series of most commonly required settings that need to be set. If you need to change some of the more advanced settings for this connection, check the "Additional Connection Settings" box (where available).

To add an new layout Connection, in the Connections pane click on the tab with a "+", this will then present you with a fresh connection tab. To remove a Connection, in the System Manufacturer drop down list, select (none selected) to just clear your present choices and enter new ones, or click on the small "x" in the Tab name to delete the Connection.

For more information on how to configure this for your particular hardware, see the Hardware Help pages.

Remember to press Save!


JMRI v4.15 Defaults Prefs tab

If you are using multiple connections, e.g. a LocoNet Connection and a SPROG Connection, the Defaults pane lets you select which connection you want to use for a particular purpose. For example, you can select one connection (LocoNet in the figure) for train throttles and consists, while using a different one (SPROG in the figure) for the service mode programming track.

For most Layout objects there is no default connection. Every time you create a Turnout, Signal or Sensor, you can choose which system ( eg. LocoNet or MERG ) it belongs to.

The Internal connection can be selected as a default. To avoid a common mis-configuration, JMRI applications will notify you if the Internal connection is selected across all the columns. If you choose to use an all-Internal set of defaults and want to silence this notification, edit the profile properties, setting the property jmri-managers.allInternalDefaults to true.

File Locations

These allow you to set the default location for where scripts and user files are loaded and stored.

Note that when changing the User Files Location, this will also change the default location for where the following are stored:

There's a separate Help page with information on sharing files between computers using Dropbox.

Start Up

Start Up preferences allow windows and files to be opened, scripts to be run, and additional buttons to be placed on the main window when the application starts.
A very common use is a load file action (see below) to automatically load your last stored layout configuration file at startup, so all your turnouts, sensors, panels etc. are available again.

Click the Add ▾ button and select the type of start up action to add. The new action will be added last.

Start up action order is important. In most cases, scripts should be the last items in the start up order. Start up order can be changed by selecting a start up item and moving it up or down in the list.

Individual start up actions can be enabled or disabled. The default is Enabled.since 5.5.6

JMRI Start Up Prefs tab

There are seven types of start up actions:

Add button to main window...
Add extra buttons to the main PanelPro window that are connected to specific actions in menus for easy and quick access to that action.
Add script to button...
Add extra buttons to the main PanelPro window to start scripts.
Load table content and panels...
Automatically load a PanelPro xml data file or Configuration file when the program starts up.
Wait a number of seconds before running the following start up actions. An example is waiting for script to finish running.
Perform action...
Have the program automatically execute various menu selections at startup. For example, you can have the Turnout Table automatically open, or automatically open a window for programming on the main.
Run script...
Automatically run a scripts when the program starts up. You can run as many scripts as you'd like; each will be run to completion before the next is started. Note that any files the script depends upon need to be loaded before running the script.
Set route...
Set a route when the program starts. You can set as many routes as you like; each will be set in order. Note that any files the route depends upon need to be loaded before setting the route.

Shutdownsince 5.1.1

When JMRI is stopped using Quit, a process is run that determines if any tables or panels have been changed since the last PanelPro store occurred. This provides an opportunity to do a final store before shutdown.

The check process uses two shutdown preferences and options for ignoring special cases that can result in unnecessary store requests.

shutdown preferences

Check for changes that have not been stored is the master switch for the process. If this is unchecked, no checking will occur. Checked is the default setting. Starting PanelPro creates some default Fast Clock table entries. If these are the only table entries, a store request will not occur.

If the check process has been enabled and there are changes that should be stored, a dialog will be displayed. The changes normally occur due to table and panel changes. They can also occur when a connection, such as Digitrax, automatically adds sensors and turnouts.

store reqquest

The default is to show the store request dialog and if Yes is selected, the actual store dialog will be displayed. The Skip option can be selected to go directly to the store dialog.

Ignore Optionssince 5.5.5

Fast clock changes
Some fast clock changes are meant to be temporary, or come from external sources. If it is not necessary to retain the changes, this option will ignore the changes.
Sensor icon text color changes
When sensor icons have been changed to text labels, sensor state changes can change the text and/or background colors. These appear to be permanent changes that should be stored but they are actually temporary changes until next sensor state change.


JMRI v4.23 GUI Prefs tab
A row of radio boxes allow you to select how the program looks. The available choices depend on what kind of computer you have, and not all of the following may be available:
  • Nimbus — An alternate style
  • Metal — the default Java style, usable on all computers
  • CDE/Motif — A Linux/Unix form that works well with X Windows screen managers. It's also available on (almost) all computer types.
  • Windows — only available on Microsoft Windows systems, this makes the program look as much as possible like a regular Windows application.
  • Mac OS X — only available on MacOS, this makes the program look like a Macintosh application.
In addition, this tab lets you set:
  • Font size — The font size of the GUI.
  • File Chooser Dialog file view — Select the file view when using the file dialogs. The options are the Default view, the file name List view and the file Detail view.
  • Use non-standard release event for mouse click? — Provide alternate mouse behavior for specific hardware.
  • Use icons to show state in tables — Whether you want to use graphics to show the state of turnouts, lights, sensors and blocks in the state column of their tables.
  • Use tabbed OBlock editing — See OBlock GUI Options.
  • Use old location and size logic for editor panels — Whether you want to use the values saved in a panel xml file instead of the standard location and size process for JMRI windows.since 4.15.6
  • Maximum Combo Box List Rows —Limit the size of combo box lists. This can be useful for large screens.since 4.23.1
  • Tool tip display time — How long tooltips (where available) should be shown.
Many people have contributed "internationalizations" of JMRI. This converts (much) of the text on the screen to a language other than English. If you select your country or region and language here, then save and restart the preferences, JMRI will use an internationalization for that country and language if it's available. Items that have not been translated will continue to appear in English, so you won't miss anything. For more information on how to set this up, and particularly how to contribute new and improved translations, please see our internationalization page.
This allows you to customize the way that the JMRI System Console looks. It is possible to select from a number of pre-defined color schemes and to choose the font size and style. Also, you can choose to save both the size and location of the System Console window so that it always appears in the same place and at the same size.


JMRI v4.17 Messages Prefs tab

This allows you to change the way that information and warning messages are displayed in JMRI.

It will also allow you to configure a default responses and the question being displayed.


JMRI v4.7 Roster Prefs tab
Programmer tab
The DecoderPro programmer allows you to select how much or how little to display of the decoder content using configurable "Programmers". You can choose the Basic or Comprehensive interface when choosing your Locomotive decoder, but this provides a convenient place to set a default so you don't have to select it each time you open a decoder.

This section also has checkboxes for options:

  • "Show empty Programmer tabs": This lets you decide whether the DecoderPro programmer will display empty panes (tabs). Some people like to see them, even though they're empty; some people would prefer not to see them, so they don't keep trying to open and look at them. We provide this preference so you can choose.
  • "Show CV numbers in tool tips": If you allow the mouse cursor to "hover" over a value in DecoderPro, a tool tip pops up with more information. Checking this box includes the CV number in that tool tip. Some people want to know the CV number, other people want DecoderPro to handle CVs entirely invisibly, so we provide an option to let you choose.
  • "Allow caching when writing index CVs for read or write operations": Some decoders require that specific values be written to "index" CVs before certain other locations can be read or written. QSI and ESU decoders use this extensively. When doing a lot of reads or writes, for example an entire decoder, the index CVs can end up being written with the same value many times in a row. When selected, this option allows DecoderPro to skip (save time on) writes of the same index value that are otherwise redundant. Don't use this (or use it only in combination with the following operation) if you have reliability problems writing decoders, as proper operation of this option depends on reliable writes.

    More detail: A single bad write with this option off trashes one CV; writing a bad index with this option off trashes the CV that was supposed to be written and the wrong one addressed by the bad write, but the write to the next CV in the sequence is OK due to the redundant next write of the index; writing a bad index with this option on leaves that badly-written index value in place, so writes a sequence of bad CV values. Bottom line: If working with a complicated decoder with lots of CVs, you need a reliable programming connection, see next option.

  • "When possible, confirm CV writes by following this with a read": When selected, DecoderPro will read each CV after writing it. If the value doesn't match, it marks the write as failed.

    If you're having intermittent trouble writing to a decoder, this may improve reliability. If DecoderPro is never able to properly write, this won't help; it only helps if the problem is occasional, and retrying will get it right more often than not.

    Some DCC systems will check for a "write acknowledge pulse" from the decoder before declaring the write a success. Those are almost as reliable as this, and much faster. So if you're using one of those DCC systems, this might not be needed. On the other hand, if you're using a DCC system that "writes blind", with no check, this might be really useful. To tell if you have one of those, try writing CVs with the locomotive off the track. If DecoderPro thinks the write succeeded, then the DCC system is writing blindly, without checking.

    This doesn't help (but doesn't hurt) if you can't read back the decoder. Most DCC systems can't read during ops mode programming, for example. Some command stations (Digitrax DB150) can't read from the decoder. In those cases, this option just asks the command station to write without reading back.

These options are stored with the preferences for future use. A new DecoderPro Roster window will pick up new values of the options, without having to close and restart the program.
Roster tab
Normally, the Roster is stored in a standard location as part of the User Files Location. This option lets you move that somewhere else.

To configure it, click the "Set..." button and follow the directions.

The "Reset" button restores it to the default location. Note that this just changes where the program looks. If you've stored roster information somewhere else and want it back in the default location, you have to move the files there yourself.

You can also enter a default value for the "Owner" field in DecoderPro roster entries here. This fills in the value for new entries, which can save you a little bit of typing. It has no effect on existing entries, even if changed.


This Preference pane tab lets you select whether the extended Throttle features are available, and which ones can be used.


If selected, listens for a packet to be sent from the connected mobile device. If WiThrottle Server does not receive any communication in the chosen time, the affected JMRI throttle will idle its train.

The chosen time is approximate; the response may be a few seconds earlier or later.

Change the port number to use. Ensure your firewall software allows this port to be used.
Only change the Port Number after stopping WiThrottle Server if there is a chance mobile devices are still connected.
Allowed Controls
Check these boxes to allow specific features to be controlled by mobile devices. This will let you to limit what users have the ability to control.
  • Track Power - Select whether mobile devices connected through this WiFi interface can control track power.
  • Turnouts - Select whether mobile devices can control turnouts.
  • Routes - Select whether mobile devices can control routes.
  • Display Fast Clock - Select whether mobile devices can display the fast clock time.
  • Turnout Creation - Select whether mobile devices can create turnouts.
  • Consists - If selected, mobile devices can build & break "Advanced Consists".
    • NMRA Format - These consists may perform better for building and controlling with WiFi devices.
    • DCC Brand-Specific - These consists should perform better when built with a WiFi device, but controlled by a throttle from the DCC manufacturer of your system.

The "Save" button at lower left puts any changed settings into effect. For a connected throttle to use the new settings, you'll have to restart JMRI (and then restart WiThrottle) as instructed by the dialog.

Config Profiles

JMRI Configuration Profiles make it easy to set up your JMRI applications to work with different setups. Each profile specifies one set of Preferences. You can then select which one to use.

For more information, see the Configuration Profiles help page.

Web Server

The JMRI Web Server lets you connect to JMRI from a web browser on your computer, tablet or phone and work with your railroad.

This tab lets you control what the web server provides. For more information, see the Web Server Preferences pane page.

Consist Control

When checked, attempt to update CV19 in the roster entry when changing the consist.


When Help ⇒ Window Help or Help ⇒ General Help is selected, JmriHelp will display the help page in the default browser.

There are three options that can be selected.

Open help pages locally
The help page installed with JMRI will be displayed. With this option, the help pages will be based on the JMRI version that is installed. This is the default option.
Open help pages online
The help page will be displayed from the website. These pages might be newer than the installed JMRI version. This option requires an internet connection. If the connection fails, the first option will be used.
Open help pages using the Web Server in JMRI
If the JMRI Web Server is active, the help will be displayed using the local content like the first option. The difference is that the formatting will be processed by the JMRI web server. If the JMRI web server is not running or there is an error, the first option will be used.

LocoNet over TCP

See LocoNet over TCP

Port Number
Specify the port for the connection (usually left at default).
Start automatically with application
Start the connection when JMRI is started.


See LogixNG Preferences

JSON Server

The JMRI JSON server is used by applications on other computers, including tablets and phones, to connect to JMRI to operate your railroad.

On this pane you can specify the port for the connection (usually left at default) and how often the server checks for whether the connection has failed via a heartbeat message.

Railroad Name

The Railroad Name tab lets you specify the name of your model railroad (module), as it is used by several server protocols.

SRCP Server

The JMRI SRCP server is a standard way of connecting "client" user programs to a "server".

On this pane you can specify the port for the connection (usually left at default).

Simple Server

JMRI Simple Server is a part of JMRIClient, a method to remotely connecting one JMRI program to another.

On this pane you can specify the port for the connection (usually left at default).


This tab sets parameters used in computing routes and speed changes for Warrants and for controlling the events that warranted trains may encounter.

Speed Name Tables

When an automatically running train encounters a Signal aspect that calls for a speed change, the speed map table provides the information of what the speed change should be. Other parameters control the way the speed change is made.

Aspect Speed Name Table

The Aspect Speed Name Table maps the speed names found in the aspects definition of a signal system to a value. It is important that all the speed names used in your signal system be listed in the Speed Map Table. Rows can be added or deleted to conform to the Signal System aspects.

The value associated with a speed name can be interpreted in four different ways when a signal aspect requires a speed change. There are four radio buttons for you to choose the meaning of the value.

  • Percent Normal - the value is a percentage of the current throttle setting as recorded or set by an NXWarrant in the command script. That is, a percentage of the "Normal" scripted speed.
  • Percent Throttle - the value is a percentage of the full throttle setting.
  • Miles per hour - the value is an absolute scale speed in miles per hour.
  • Kilometers per hour - the value is an absolute scale speed in kilometers per hour.

Choosing the interpretation is a matter of what you want to happen when a warranted train reaches a signal or block aspect. Percent Normal will always make the train change speed and Percent Throttle most likely will also. The last two choices are the most prototypical, but if the train is already within the speed limit called for, no speed change will occur.

Head Appearance Name Table

The Head Appearance Table is used when Signal Heads are used as signals. It maps signal head appearance names to aspect speed name which in turn are mapped by the Aspect Speed Name table to values that interpret speed limits.

Layout Scale and Search Depth

It is important that the correct Layout Scale is chosen since it is needed to convert throttle settings and track speeds to and from scale speeds.

The Max Number of Blocks in Route is the depth to which JMRI will search for a route when defining a warrant. This is a global value that can be overridden when creating a warrant.

Ramping Speed changes

The smoothness for slow down and speed up are done by stepping up and down with two "ramp" parameters; the throttle increment per step and the time interval of each step. These two parameters are paired to make a "stair step" pattern for changing speed. Generally, they are paired in that a small throttle increment should be done in a short time interval and a large increment in a longer time. When setting them, the time interval should be long enough for the speed increment to complete given the momentum you have programmed into your decoders.

  • Ramp Step throttle Increment This value is a percentage of full throttle. Seven or eight speed steps of a 128 step throttle is an appropriate increment for a locomotive with modest momentum. A value of 3.0% to 5.0% is recommended. (0.08% would be 1 step of a 128 step throttle)
  • Ramp Step time Depending how you have configured momentum on your locomotives, adjust this value so the speed change is completed within this period of time. Typically corresponding to the above, 1000 milliseconds would be appropriate.

You should experiment by watching how NX Warrants start and end or by issuing "Stop" and "Resume" commands to a recorded warrant.

Throttle Factor

The value of Throttle Setting/Speed Factor along with Layout Scale adjusts a throttle setting to be a layout track speed. The Throttle Factor set here is a global default.

For more information on Warrant speed parameters, see Modifying Warrant Speeds and follow its links.

Merging Speed Profiles

since 4.19.2Warrants can compute a track speed when traversing a path with known length and known throttle setting. These measurements are made for each Roster Id that is run under a warrant and are kept for the entire layout session. When JMRI is quit, at shutdown, these Session Speed Profiles may be merged into their Roster Speed Profiles. The following choices are available at shutdown.

  • Don't Merge - Do not prompt and discard the Session Profiles and leave the Roster Speed Profiles unchanged.
  • Prompt Merges - At shutdown at dialog is presented where you may choose which speed profiles shoud be merged and which discarded. The dialog allows you to view the profiles for each address. Displayed are: the current Roster Speed Profile, the potential Merged Speed Profile and the Session Speed Profile. (default)
  • Merge All - Do not prompt and always merge all Session Speed Profiles into the Roster Speed Profiles.

Tracing Warrant Activity

since 4.24.5A record of the warrants that have been run can be output to the console. This can be done in lieu of using the "Open Session Log" menu item to write the record to file. Press this button to enable or disable the feature.

Slow Speed Assistance

since 4.24.5The ramping parameters and speed interpretation apply to all locomotives when speed changes are required by signal aspects, obstacles ahead or a user "Halt" control command. You may have a balky engine in your fleet that may not perform well at low throttle settings. Should such a speed be specified before entering a block, the engine might stall and never get there. "Slow Speed Assistance" can be given when a train is inordinately late in getting to the next block of the script. This done only when the train approaching the block has a speed less than a specified throttle setting. If the train has not reached the block within 10 seconds of its scheduled script time, its speed is increased by one "Ramp Step Throttle Increment". This is done at 10 second intervals until either the train reaches the block or has attained the specified throttle speed. Upon entering the block the original script speed is restored.

The default setting for triggering Slow Speed Assistance is 10% throttle. Slow Speed Assistance is disabled by setting the trigger speed to 0%.