JOSM/Installation
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.
Requirements
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:
- Often Java is already installed. If not, install Java. You may want to disable the browser plugin, which is not needed for (and even cannot be used with) JOSM, for security reasons.
- See https://josm.openstreetmap.de/wiki/Download#Java for more up to date Java information.
- If you currently have an older version of Java installed it is best to upgrade, but the JOSM Software Requirements detail some version compatibility options.
- 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
Download
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.
Troubleshooting
JOSM seems to start okay, but the window is blank
If you are using Wayland/Sway
- Set the
_JAVA_AWT_WM_NONREPARENTING=1environment 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, addexport _JAVA_AWT_WM_NONREPARENTING=1in/etc/profile.d/openjdk6.sh. - If you are using
jre7-openjdk, addexport _JAVA_AWT_WM_NONREPARENTING=1in/etc/profile.d/jre.sh.
See also
- Install Notes in JOSM wiki