Java Runtime Environment

From OpenStreetMap Wiki
Jump to navigation Jump to search
Java mascot “Duke”

Java Runtime Environment is a part of the Java platform. The Java platform refers to a group of software products from Oracle. The platform is used to develop and run Java programs. The platform includes the execution engine (called a Java Virtual Machine) that allows the same Java program file to run on different operating systems. This is a big advantage.

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.

Also see Wikipedia's explanation of Java Runtime Environment.

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 (like the OSM editor JOSM) but frequently pose a security risk. You also could disable the browser plugin afterwards or use your browser's controls to disable or enable.


  1. Download the installer from or pick "JRE" at if you want to use a new, not yet mainstream, version.
  2. Run it (in case you need them, instructions are linked on the download page).
    • The default options are generally okay (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.
      • It is also a good idea to not install the browser plugin or disable "web content" afterwards in the Java settings (see above for more info).
      • Maybe you would also want to disable the 'java update checker' since this will add a new auto 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).
      • Good news: At least the current 64 bit offline installer (only this was tested) for Oracle's Java 8 seems to not contain crap software. Also it seems not to enable "web content" (browser plugin) by default.

Mac OS

Minimum system requirements

Java JRE 9: Mac OS 10.10+

Java JRE 8: Mac OS 10.7.3+

Java JRE 6 (provided by Apple): Mac OS 10.5 – 10.6 only

Java JRE 1.5 (provided by Apple): Mac OS 10.4

Check which Java version you have in Mac OS

There are several ways to figure out which version of Java you have:

  • System prefs method: Under 'System preferences' see the 'java' icon, then got to 'update' tab to see if you're up to date.
  • Terminal method: Open a terminal and type: java -version. Ideally the output would look somewhat like this (in this example it is Java version 7):
java version "1.7.0_40"
Java(TM) SE Runtime Environment (build 1.7.0_40-b43)
Java HotSpot(TM) 64-Bit Server VM (build 24.0-b56, mixed mode)

Download Java from Oracle for Mac OS

  1. If you're upgrading from a earlier Java version you may have to uninstall it before. More information about how to install and uninstall Java on a Mac can be found on Note if you use the Chrome browser, this could cause very very few websites (those which use java) to stop working.
  2. Download the installer from
  3. Install from the dmg file as usual. For more info see the links there to Oracle's "install guide" or "system requirements" for Java on Mac OS.

For how to run a Java program, see the section further down this page.


  • 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 in the default repositories. Some distribution-specific instructions follow.
  • Alternatively, install Oracle's Java from Multilingual install help available (e.g. German, Japanese, Russian).

Arch Linux


See refer to "User documentation" section at debian wiki.

Or see the following older info. "Older" because Java Version 6 is totally outdated. You likely want to use a newer one and OpenJDK.
  • enter (as root):
    $ apt-get install sun-java6-jre

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


See "Installing a JRE/JDKs" section at gentoo wiki.

Or see the following older info. "Older" because since "sun" likely the wrong package name as this is the old Java producer.

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.


See the "Installing Java" article at the openSUSE Support Database.


See for example …


See the guide at

How to run a Java application

Many Java applications come packaged as a file with the ".jar" extension. In most operating systems there are those two ways to run Java applications: double-clicking and via a command terminal. Both are described in the following sections.

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.

This is also an security issue. Think twice before you set up your system to start jar files automatically by just clicking – this would work with all downloaded jar files then (also with accidental, malicious downloads)! Better use the command line or a manually built link/script.

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 hard even if you don't have any experience of command lines. For example for to run JOSM, open your command terminal and type those commands (example for the program file josm-tested.jar):

  1. Change to the directory where josm-tested.jar is. If it's on your desktop, try 'cd Desktop': cd path_to_the_directory_that_JOSM_is_installed_in
  2. start the application: java -jar josm.jar
  3. done – the application (JOSM) runs!
  4. Tip: Often you want to allocate more memory to the application (possibly in order edit larger map areas in JOSM or if you get the 'strange things may happen' memory error). Use a Java option (also see the section below) to do so: java -Xmx1024M -jar josm-tested.jar

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: 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 double-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

In Mac OS 10.4 or later simply double click on a application's jar file and Java should load the .jar file.

Note that the JRE download (as opposed to the JDK download) from Oracle does not replace the shortcuts like "java" in your command line Terminal (see [1]). To access the JRE from the command line use /Library/Internet\ Plug-Ins/JavaAppletPlugin.plugin/Contents/Home/bin/java instead of just java. Some application launchers, e.g. JOSM's, still work with the JRE (find them automatically).

Special options for Mac OS

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

Creating a start application with Jar Bundler

If you're not familiar with creating scripts just use the Jar Bundler application, coming with Mac OS. 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 application.

Via shell scripts (Linux, FreeBSD, Mac OS)

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 for specific applications; for example see JOSM/Linux#Start JOSM.

Options for application execution

You can add options on the command line, in the command of your shortcut, in your script or – depending on your system – in an environment variable (_JAVA_OPTIONS). 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, 1024 MB with the option "-Xmx1024M". (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.
nicer graphics
  • -Dawt.useSystemAAFontSettings=on -Dswing.aatext=true switches anti-aliasing (smoother edges on text) on

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