Java Runtime Environment

From OpenStreetMap Wiki
Jump to: navigation, search
Available languages
English 日本語
Java mascot “Duke”

See Wikipedia's explanation of Java Runtime Environment.

Pure Java applications have a big advantage. They can run on any operating system without the need for developers to prepare a binary package or a installer for each operating system. On the other hand java applications do require a "Java Runtime Environment" (JRE), and this installation does depend on the operating system you are running. This page explains how to install JRE on your machine and how to run a Java application though the Java runtime.

Much software in the OSM ecosystem depends on the Java Runtime Environment:

How to install

If you are not interested in running applets inside the web browser you might choose not to install any browser plugins/extensions. They are not needed for running Java desktop programs but frequently pose a security risk. You also could disable the browser plugin afterwards or use your browser's controls to disable or enable.


  • Download Java SE Runtime Environment Installer from here:
  • Just run the installer
    • All the default options are generally the most sensible (installs to "Program Files/Java") except …
      • It is a good idea to not install any additional advertised crap software (search bars, security checkers, …) – uncheck this during the install procedure.
      • Maybe you would also want to disable the 'java update checker' since this will add a new start-up item (one of those things which slows down start-up times very slightly). However, then you need to manually check for new Java versions (important if you use the browser plugin/extension).

Mac OS X

  • Java 7 and later is not provided by Apple. You must download it on
  • See here for detailed explanations.

Because JOSM requires Java 7, we're finding all sorts of fun problems with getting it working on various version of MacOS at the moment. See JOSM/Mac#Installation for more information.


  • Use your distribution's package installer/manager to install a Java VM (JRE). This will automatically keep the Java version updated. Often the JRE from OpenJDK, the free software version of Oracle's implementation, is available there. Distribution-specific instructions follow.
  • Or install Java Runtime from


8.10 (Intrepid):

The latest version of JOSM and all the associated packages can be installed very simply with Ubuntu's Synaptic Package Manager.

  • Open Synaptic Package Manager (System >> Administration >> Synaptic Package Manager). Select All at the top of the list of software categories and type JOSM in the search box.
    • if JOSM doesn't appear in the package list make sure you have enabled Community-maintained open source software (Universe) in the Software Sources manager (System >> Administration >> Software Sources >> Ubuntu Software)
  • Check the box next to JOSM and mark it to be installed.
  • Click the "Apply" button on the top navigation bar. Allow the associated packages to be downloaded; JOSM will be installed on your system.
  • a quick link to JOSM can be found in the Applications >> Education menu; or you can open a terminal and type josm
Custom install on older versions of Ubuntu:
  • Install Java:
    $ sudo aptitude install sun-java6-jre
  • If you want to have sound for audio mapping and you are using ALSA (default in ubuntu), install alsa-oss:
    $ sudo aptitude install alsa-oss
  • launch JOSM:
    $ aoss java -jar /usr/share/josm/josm.jar

Be sure to adjust the path to your josm jar file.

  • Note: For some reason josm won't play sounds using Sun's JDK, so if you're doing audio mapping use openjdk-6-jdk instead - you'll have to set JAVA_HOME since josm doesn't obey /etc/alternatives/java - see /usr/bin/josm for more.
  • Since Ubuntu 8.04 LTS JOSM is in the universe repository:
    $ sudo aptitude install josm
  • If you want up-to-date packages in Ubuntu 8.04 (updated nearly every day), you can use the PPA from The Launchpad OpenStreetMap Team


  • enter (as root):
    $ apt-get install sun-java6-jre
  • Debian Lenny has JOSM (optionally some josm plugins) in the repository:
    $ sudo aptitude install josm josm-plugins

Note: If you have another JVM installed and want to use SUN's java, start josm with

JAVACMD=/usr/lib/jvm/java-6-sun/bin/java josm


Standard installation with Portage:

emerge -av sun-jre-bin

Gentoo ebuild collections has some OSM Java applications. By installing one of it, you can install the JRE as a dependence. For example:

emerge -av josm

There are many plug-ins already available as ebuilds. Look at for a complete list. If you are interested in latest development version of java applications and extra plugins of them use the OpenStreetMap Gentoo Overlay.


JOSM packages are available in the openSUSE's build service, in the Application:Geo repository.

Go to, select you distibution and find the RPM in the noarch directory. Install using RPM or your favourite package manager.

Example for openSUSE 10.3 using zypper:

zypper ar
zypper ref
zypper in josm

The first command has changed slightly for openSUSE 11.0 (and openSUSE 11.1):

zypper ar
zypper ref
zypper in josm

Use this for openSUSE OneClick install:


You can get a JRE binary package from . Installing the binary package as like this:

pkg_add diablo-jre-freebsd7.amd64.

Of course, you can install JRE from ports collection:

cd /usr/ports/java/diablo-jre16/
make install clean

However, I don't recommend to compile JRE by ports because it takes long time and it needs JDK (Java Development Kit) to be installed. The JDK would be installed by using the package as the above and the JDK can run Java application, too. So compiling JRE is nonsense for you unless you want to be a FreeBSD ports developer.

How to run a Java application

Many Java applications come packaged as a file with the ".jar" extension

Double-click a jar

Many jar files are "runnable". This means you can simply double-click the file on many operating systems. The file contains details of which java class files to run by default, and the application just starts up. Easy!

This assumes a few things though. Firstly you'll need java installed as detailed above, and with the necessary operating system hooks enabled, and these may not be available for some operating systems.

Run it on a command terminal

This way is a more basic fundamental approach which you can use on any operating system. Some Java applications (for example, mkgmap.jar) cannot run without terminals.

It's not so hard even if you don't have any experience of command lines. For example for to run JOSM, type commands like this:

cd path_to_the_directory_that_JOSM_is_installed_in
java -jar josm.jar

then the JOSM runs.

You can add options on the command line. There are two kinds of options. One kind for initialising the Java Virtual Machine, the other for application options.

java [Options for JavaVM] -jar application.jar [Options for the application]

The following are commonly used options for the Java VM.

memory options
  • -Xmx is the only memory option which really matters. This is the maximum memory capacity of the Java application. The default value is 64 MB which is often too small. Increase it to, for example, 512 MB with the option "-Xmx512m". (other java memory options)
proxy options
  • -Dhttp.proxyHost= specifies a proxy server if you want to use http though a proxy server. For example, "-Dhttp.proxyHost=".
  • -Dhttp.proxyPort= specifies a proxy port. The default value is 80. For example, "-Dhttp.proxyHost=8080".
  • -Dhttp.proxyUser= specifies proxy user name. Set it if the proxy server requires authentication.
  • -Dhttp.proxyPassword= specifies proxy password. Set it if the proxy server requires authentication.
  • Specify it, if you need IPv6. By the way, the OpenStreetMap-server doesn't support ipv6 yet.
graphic accelerations
  • -Dsun.java2d.opengl=true Enabling OpenGL. Specify it if you know your PC has OpenGL 2D graphic accelerators. If you have problem with this setting (false icon and background, dialog. tested on WinXP + nVidia FX1500 + dual monitor) use:-Dsun.java2d.opengl=true -Dsun.java2d.opengl.fbobject=false although note that the opengl option can cause problems with window managers on Linux.
  • -Dsun.java2d.d3d=true -Dsun.java2d.ddscale=true Enabling DirectX graphic acceleration for Windows.

The options for the application depend on each applications. See their page for these.

Where is the command terminal?

  • Windows:
    • Click the "start" button. You can find "Command Prompt" in "Programs/Accessories". If you don't find it, you may be missing this shortcut, however you don't need it...
    • Click the "start" button then click "Run..." and enter "cmd" in a box on the Run window.
    • Alternatively create a file 'run-josm.bat', and edit it in notepad. Enter your command as the only contents of the file. Save it, then double-click the file to run it. If the black command window disappears immediately, you can debug by adding a new line 'PAUSE' in the bat file.
  • Mac OS X: Go to "Applications" and then "Utilities" in Finder. You will find "Terminal".


Usually, the JRE installer registers the .jar file type to be run by javaw.exe (which is another java running command. It is special for Windows to run Java GUI applications without terminals.) command. So you can run .jar just by doble-clicking it. However, this way cannot add options. To add options, you can choice from two ways.

  • Making a .bat file.
    1. Open a text editor (for example, notepad) and create a new file by it.
    2. Write commands on it. I recommend to write a "cd" command before "java" command to specify the default running directory.
    3. Save it as .bat file (for example, josm.bat).
    • When you double-click the .bat file, a command terminal opens and do the commands on the .bat file.
  • Making a shortcut. (.lnk file)
    1. Right-click on a .jar file. Click "Create Shortcut" on the pop-up menu. (You can use "Send to/Desktop (create shortcut)", too.)
    2. Right-click the created shortcut and select properties.
    3. The full path of .jar file is shown on Target box. Add "javaw [Options for JavaVM] -jar " before the .jar path. Add " [Options for the application]" after the path.
    4. If you need to specify the current directory when it runs, you can write it in "start in" box.
    • When you double-click the shortcut, it runs the application with the options.
    • The shortcut is free to move, to rename and to change the icon. I recommend it to rename it to the application name (eg. "JOSM" without "shortcut to"), and to move it to under the "start menu".

Mac OS X

You need Mac OS 10.4 or better. 10.3 will not do the job. In 10.4.x and 10.5.x, simply double click on the jar file and Java 1.5 should load the .jar file. If you need to allocate more memory (in order to edit larger files or you get the 'strange things may happen' memory error),

  1. Go to Applications and then Utilities in Finder.
  2. Open Terminal
  3. Change to the directory where josm-latest.jar is... If it's on your desktop, try 'cd Desktop'
  4. Copy and paste the following line in to the terminal to start JOSM with more memory:
java -Xmx512M -jar josm-latest.jar

Include -Dapple.laf.useScreenMenuBar=true to place the menu on the OS X menu bar, and -Xdock:name="JOSM" -Xdock:icon="logo.png" to give it icon and name.

If you're not familiar with scripts just use the Jar Bundler application, coming with MacOS X. It'll create a start application, let's call it "JOSM!". You'll find it here /Developer/Applications/Java Tools/ or here /Developer/Applications/Utilities/. Just double click to launch it. In the first menu build information enter the location of the just downloaded JOSM jar file by clicking the choose... button. In the third menu properties choose the edit box vm options to enter the appropriate memory settings. If you're able to afford it try spending up to a GB RAM to JOSM. Here's what to enter into the edit box: -Xmx512M -XX:MaxPermSize=512M (which starts the JOSM application with 512MB and grants up to 1GB of RAM). Then press create application... to create the start application (call it JOSM!, f.e.). JOSM! does not have to be in the same directory as the jar file. Just save or move JOSM! to your applications folder. Double click JOSM! to start the JOSM aplication.

Linux, FreeBSD, (Mac OS X with a terminal)

Input a command line as the above is the basic. Usually the command line become long. It is better to make a shell script to run for each jars. There are some users make some useful shell scripts.

You can use a shell-script developed by User:Cobra to keep JOSM always up-to-date, start it, and pass files to it.

Or you can use the following simple script to use always the latest Josm Version:

export JAVA_HOME=/usr/local/java/jdk1.6.0_04/
DCOPREF=`kdialog --title "Hole JOSM"  --progressbar "Hole JosmLatest" 100`
wget -N
dcop "$DCOPREF"  close
$JAVA_HOME/bin/java -Xmx1024M -DproxyHost=$PROXY -DproxyPort=8080 -jar josm-latest.jar

If you use Ubuntu 8.04 LTS or Debian and install JOSM via package, you will simply use josm.

Ubuntu users have a good tutorial at UbuntuForums.

There are also some tutorial videos. One describes the steps to set up KDE for starting JOSM by clicking on the JAR file. Get the tutorials from one of the mirrors listed at