From OpenStreetMap Wiki
Jump to navigation Jump to search

JOSM installation is very simple. Just download and run the jar file or use Web Start). However, this may not always work. This page gives more details about system requirements, links to help you understand how the JOSM application runs, how to set it up most effectively, and how to troubleshoot various installation problems.

Once you've done that step, see JOSM/Guide for the usage of JOSM.


In order to run JOSM on your computer you'll need:

  • Java 8 (Java versions 9-17 are also supported, with Java 17 being preferred). Notes:
  • 512 MB RAM or more
  • A display resolution of 1024×768 or higher (800×600 won't be much fun)
  • (recommended) a graphic adapter with 2D acceleration turned on for more speed


JOSM can be downloaded from the JOSM homepage.

"tested" or "latest"?

The choice between "tested" or "latest" may depend on whether you are keen to help with testing the latest features. josm-tested is a "stable" version of the application, meaning it has been baselined at a stable point of development. josm-latest is a version with all the latest features but also all the latest bugs. Working with josm-latest is helpful to the project (you can help report bugs and suggest features). Currently it can also be more trouble-free due to the way plugin versions are managed. Note that josm-tested will try to load the latest version of any plugins if you automatically install/upgrade them, and these may then complain about needing a later version of JOSM! At some point we hope to improve the release process for new plugins.

Secure download

The download links here should point to SSL/HTTPS-secured downloads on the JOSM website by default. Usually, no other effort is needed to be made by you. The JOSM website currently uses a certificate signed by the “GlobalSign” CA. If you do not trust this CA you could compare the fingerprint on an external source.

Many Linux distributions offer JOSM packages, see JOSM/Linux. Using Linux-distro specific installation methods is an alternative to the download via HTTPS although the installed version may be older than what is available from JOSM directly. A benefit may be the automatic JOSM update by your distribution's package management system.

Start JOSM

The jar file needs to be passed to the Java runtime.

Usually, you can just double click on the josm.jar file in GUI Operating Systems. (Windows, macOS, some Linux distributions). If it doesn't work or if you need to set options, see How to run a Java application.

JOSM can need quite a lot of memory. Java's default maximum is fairly stingy. Set an option -Xmx1024m to extend usable memory

Options to enable 2D graphic accelerators (ex. -Dsun.java2d.opengl=true) are recommended. To get verbose feedback when enabling works, use -Dsun.java2d.opengl=True (note the uppercase T in this case).

Per platform instructions

JOSM is a Java application. It can run anywhere where the Java platform can run, but there are peculiarities on various platforms and operating systems. For specific instructions please see the following sub-pages:

For running JOSM from a flash disk:

Upgrading JOSM

JOSM will automatically check for updates and tell you about updates in its startup screen. To manually check: You can find which version of JOSM you have by using the 'About' menu option in the program itself. The JOSM website indicates what the 'current' version is (current latest and current tested).

If you decide you want to upgrade, the steps are broadly speaking as follows. This only applies if you do not use the "Java Web Start" option (it will update automatically via Web Start).

  • Download the JOSM jar file again.
  • Find where your existing jar file was.
  • Delete it or rename the old jar file and place the new one in its place.

However, the exact approach you used to install JOSM may mean it's difficult to find the jar file, and there may be alternative (better) means of upgrading, e.g. using package managers or re-installing from an installer. Please follow the relevant link in the section of above for platform specific instructions.


JOSM seems to start okay, but the window is blank

If you are using Wayland/Sway

  • Set the _JAVA_AWT_WM_NONREPARENTING=1 environment variable.

If you have the fancy, compiz/beryl graphics stuff enabled, then this may happen. The solution is simple, add the following line to the user profile:

export AWT_TOOLKIT="MToolkit"

or put this in the "Run Application" dialog:

compiz --replace && export AWT_TOOLKIT=MToolkit

This also happens under tiling window managers such as ratpoison and stumpwm with Java 6 VMs (no problem with IcedTea/Java 7). It seems like JOSM demands to adjust its geometry in a certain way and when it can't panics.

  • This workaround is not needed for OpenJDK 1.6 with StumpWM git as of 2009-02-28.

A workaround is either to launch JOSM under Xnest, or in a separate X server. To start ising Xnest:

Xnest :1 -ac -geometry 1280x1024
DISPLAY=:1 java -jar josm-latest.jar

You may also need a window manager, this example uses fluxbox:

Xnest :1 -ac -geometry 1280x1024
fluxbox -display :1
DISPLAY=:1 java -Xmx1024m -jar josm-custom.jar

Similarly, to launch under Xephyr (an alternative to Xnest):

Xephyr :1 -ac -screen 1280x1024
DISPLAY=:1 java -Xmx1024m -jar josm-latest.jar

One could also export the AWT_TOOLKIT variable above but that doesn't seem to work for certain things, e.g. the download dialog is zero-sized.

To use another instance of the X server (a dedicated $DISPLAY for JOSM):

X :1
fluxbox -display :1
DISPLAY=:1 java -Xmx1024m -jar josm-latest.jar

Now you can switch between displays using Ctrl+Alt+F7 and Ctrl+Alt+F8.

A workaround for many java+tiling window manager related problems is to:

  • If you are using openjdk6, add export _JAVA_AWT_WM_NONREPARENTING=1 in /etc/profile.d/
  • If you are using jre7-openjdk, add export _JAVA_AWT_WM_NONREPARENTING=1 in /etc/profile.d/

See also