JMRI Setup: Configuration Files
This section attempts to explain where JMRI Configuration (settings) Files are stored on
your computer and what information they contain.
- Configuration File Locations
There are two places where JMRI Configuration Files can be found:
- The originally-distributed versions of JMRI Configuration Files live in an 'xml'
directory in the JMRI application package and its subdirectories. (The exact location
depends on how you installed JMRI on your computer)
Note that anything you modify here will be lost when you update JMRI to a new
version. This is not the right place to make changes!
- The user's JMRI Preferences directory and its subdirectories is also of importance.
JMRI looks here first for any files it needs.
You should put any locally-modified versions of files here so they don't get
overwritten by a JMRI update. Any files that the program writes to containing local
information, e.g. Roster entries and Panel files, are also written here.
The default user's Preferences location varies by computer operating system.
Normally, it's located:
The easiest way to find the preferences location is to start a JMRI program, e.g.
DecoderPro or PanelPro, select "File Locations" from the "Help" menu and click on [User
- On a Linux machine, look for a
.jmri directory in your home
- On macOS, Preferences are stored in a "JMRI" folder in the
- On Windows, this can be in a number of places depending on the Windows version
you're running and whether you have multiple users configured. Start by looking
under "Documents" or "User Documents" or "Users and Documents". You're looking for
a folder called "JMRI".
A special treat for Windows users: if you go to the Windows Start Menu, in the JMRI
section, you can select "Preferences" to have it open that directory for you.
- User files can be stored under the preferences location, but JMRI can also be
configured to put them somewhere else.
You may set or change the location scripts and user files in the Preferences... -> File
Locations panel. Note that changing the "User Files Location" will also change
the default location for Panels, Rosters etc.
- Types of Configuration Files
Inside your JMRI Preferences folder are a number of types of configuration files used by
- Decoder definitions - Stored in the decoders subdirectory, one for
any customized decoder; these define how a specific family of decoders is
- Locomotive configurations - Stored in the roster subdirectory, one
for each Locomotive; these record the specific configuration of each Locomotive in your
- Programmer definitions - Stored in the programmers subdirectory
when you've used at least one Programmer; these define the formats for the various
programming sheets that are available in DecoderPro.
- The DecoderPro folder, containing your profiles.
- General Configuration Files
There are many more JMRI Configuration Files, some shared by applications, which live in
the user's Preferences directory:
roster.xml - an index of your Locomotives
decoderIndex.xml - an index of the available decoder definition files.
It also contains the information on which specific decoder model uses which file, how
to identify them, and what options they implement.
names.xml - not used during normal operation, this is a list of the
standard Variable Names for use in programmer definitions.