Command Line Options

JOSM is affected by three groups of command line options. The Program arguments⤓ are most important and than the Java options⤓. See the examples⤓ for both of them. Only involved in Web Start are the run-options⤓. The last section here deals with other⤓ options which are used somewhere in this help pages.

# Running a jar
java [Java options] -jar josm-tested.jar [Program arguments]

# Launch a Web Start
javaws [run-options] -J[Java option] josm.jnlp

Program arguments

Also called Post jar arguments here or args by Oracle.

The first argument is seen as command by JOSM. The possible commands are runjosm for normal launch (default), render for generating an image file and project converting coordinates. If JOSM can't recognize a command the default is assumed.

The following arguments are options for JOSM. They are separated by spaces. They can be URLs, filenames, coordinates, simple options and option=argument pairs. The complete list of commands and options is shown below:

usage:
  java <java options> -jar josm.jar [<command>] <options>

commands:
  runjosm     launch JOSM (default, performed when no command is specified)
  render      render data and save the result to an image file
  project     convert coordinates from one coordinate reference system to another

For details on the render and project commands, run them with the --help option.
The remainder of this help page documents the runjosm command.

options:
  --help|-h                                 Show this help
  --geometry=widthxheight(+|-)x(+|-)y       Standard unix geometry argument
  [--download=]minlat,minlon,maxlat,maxlon  Download the bounding box
  [--download=]<URL>                        Download the location URL which has
                                            coordinates like lat=x&lon=y&zoom=z
  [--download=]<filename>                   Open a file (same as Menu/File/Open)
  --downloadgps=minlat,minlon,maxlat,maxlon Download the bounding box as raw GPS
  --downloadgps=<URL>                       Download the location as raw GPS
  --selection=<searchstring>                Select with the given search
  --[no-]maximize                           Launch in maximized mode
  --reset-preferences                       Reset the preferences to default
  --load-preferences=<url-to-xml>           Import preferences from XML file
  --set=<key>=<value>                       Set preference key to value
  --language=<language>                     Set the language
  --version                                 Displays the JOSM version and exits
  --debug                                   Print debugging messages to console
  --skip-plugins                            Skip loading plugins
  --offline=[osm_api,][josm_website,][all]  Disable access to the listed resources

The --download= part of the download option is optional. The arguments --download, --downloadgps and --selection are processed in this order. The value <url-to-xml> can point to a local file with file:relative/path/name.xml. More verbose than --debug is the --trace option. The items in the --offline value are separated by comma.

Java options

The Java options are also called JOSM JVM options here or VM arguments in the Status Report. In that report you can see them and also the Program Arguments. They control the Java virtual machine ​(JVM) and can set ​properties inside it. JOSM reads some of them, for example josm.home and user.language.

java options:
  -Djosm.dir.name=JOSM                      Change the JOSM directory name
  -Djosm.pref=/PATH/TO/JOSM/PREF            Set the preferences directory
                                            Default: C:\Users\name\AppData\Roaming\JOSM
  -Djosm.userdata=/PATH/TO/JOSM/USERDATA    Set the user data directory
                                            Default: /home/name/.local/share/JOSM
  -Djosm.cache=/PATH/TO/JOSM/CACHE          Set the cache directory
                                            Default: <...>
  -Djosm.home=/PATH/TO/JOSM/HOMEDIR         Set the common directory for preferences,
                                            user data and ./cache/. Lower precedence.
                                            Will get overridden from specific setting.
  -Xmx...m                                  Set maximum Java heap size in megabytes.
                                            May avoid Out-of-Memory errors.

The -Xmx...m option may be useful when Out of Memory errors arise. If you set a common directory with Djosm.home then JOSM will create the subdirectories ./autosave, ./cache and ./validator. If a value has spaces, then enclose it in quotation marks like "josm dev".

Examples

Examples for the Program arguments and Java options in action:

# Load three files
  java -jar josm.jar track1.gpx BigBen.jpg "london data.osm"
# Download from OSM according to an URL with zoom and coordinates
  java -jar josm.jar https://www.openstreetmap.org/#map=19/51.51/-0.135
# Download a bounding box and select every element matching a string
  java -jar josm.jar 51.505,-0.14,51.515,-0.13 --selection="Piccadilly Circus"
#
# Set directory for JOSM according to a property from the operating system
  java -Djosm.pref=$XDG_CONFIG_HOME jar josm.jar
# Quotations for a value with space
  java -Djosm.dir.name="josm dev" -jar josm.jar
# Set the common directory in a sub-subdirectroy below the active command prompt
  java -Djosm.home=biketour2017/london -jar josm.jar
# More memory in a French spoken environment
  java -Xmx1024m -Duser.language=fr -jar josm.jar
#
# Do not get disturbed by phoning home and log debugging info in English
  java -verbose -jar josm-latest.jar --set=message.notifier.enabled=false --language=en --debug >WhatsUp.txt

run-options

The run-options follow the javaws command. They control the Web Start mechanism and the environment for the JVM.

  -offline                  Allows to Web Start JOSM without internet access
  -J<java option>           Supplies the <java option> to the JVM 
  -J-Xmx1024m               Here: Set maximum Java heap size to 1024 megabyte

The -J run-option takes its part behind the J letter and supplies that as Java option. The jnlp-File used by ​Web Start offers a second way to ​set options for JRE and for the JOSM program directly.

Other options

The javaws command on all systems and the josm.exe on MS Windows have some additional ​options.

javaws -viewer            Shows the Cache Viewer in the Java Control Panel 
# Allows to opens the Java Control Panel from the command line.

javaws -clearcache        Removes all non-installed applications from the cache
# Equal to 'Delete Files and Applications' from the 'Temporary File Settings' invoked 
# by the 'Settings' button in the 'General' tab of the Java Control Panel.
# javaws -Xclearcache on OpenJDK

josm.exe --j4l-debug      Tries to write a launch4j.log to current directory
josm.exe --j4l-dont-wait  Ends the wrapper after invoking JOSM.

Deleting temporary files will delete JNLP based icons from the Desktop too.

See also

• Troubleshooting Java
• Installation notes
• Preferences - overview page about all "preferences"