TOC(inline)

Semi-Stable Version

The latest semi-stable version is always here: josm-tested.jar - we don't call it a "release" because while it is more robust than the nightly build, it doesn't usually run through as many checks as a release would.

Nightly Builds

You can always grab the latest nightly build from josm-latest.jar. Many users actually use this for their daily work.

Running

A working Java Runtime Environment version 7 (32 bit package ONLY, 64 bit package don't provide the trues libraries) or newer is needed to run JOSM.

Microsoft Windows

Double click on the jar file.

If this does not work, you probably need to install the ​Java Runtime

In more extensive edit sessions, you may get an "out of memory" error. To avoid this, the assigned memory can be increased.
Create a shortcut like in the following example:

java.exe -jar -Xmx2048M "C:\PATH-TO-JOSM\josm-latest.jar"

To avoid the Java console windows staying open, you can use javaw.exe instead of java.exe.

Be carefully if you run a 64 bit version of Windows, the Java Runtime (update every month) is installed in 64 bit.

But, the JAR extension only be launch with the 32 bit version of the Java Runtime (program files (x86) folder - "bin" folder) since the v8u66.

Visit the www.java.com main site, choose to download java ... and chose the i586 package. You can keep the 64 bit package because it is not installed at the same location than the 32 bit (i586) package.

Linux / *BSD

packages

In some Distributions prepacked packages exist to install JOSM with your favorite package manager from the repositories. Although these packages might be a bit older than the .jar files on the main page, they usually fit better into the environment and install dependencies and a starter in the menu automatically.

Note: There is no problem with installing the prepacked package and still using the .jar files listed above but be careful with additional packages like josm-plugins (see #7483).

For SUSE and Ubuntu there are also packages on this page available. If there exists no package or you do not want to use it you can download the JOSM .jar file from the main page (tested or latest version) or build it from source.

using the shell

Go to the directory where the josm-latest.jar is and type

java -jar josm-latest.jar

to launch. Replace josm-latest.jar with the name of the jar file you loaded, e.G. josm.jar for releases.

If this doesn't help, try to set your JAVA_HOME variable to the java location (the root location, not the bin. As example:

 export JAVA_HOME=/usr/lib/jvm/default-java
 java -jar ''josm.jar''

See also command line options and Josm under Linux Howto for additional info.

KDE

There is a tutorial on how to setup your environment to start jar-files by clicking on them.

GNOME

Right click on the JAR file, and select Open with "OpenJDK7 Runtime", or whatever Java version you have.

XGL/Compiz

Type this into a shell:

export AWT_TOOLKIT=MToolkit && java -jar josm-test.jar

as described here: ​http://kubasik.net/blog/index.php/2006/06/19/java-sun-150-and-xglcompiz-on-ubuntu/

Blank window on startup

AWT before JDK7 ​doesn't play well with non-reparenting window managers (i.e. xmonad, awesome, dwm, ratpoison, Ion3, ...), resulting in the main window not being displayed properly on startup. The Awesome Wiki has ​workarounds for this problem. There is also an ​xmonad specific way of doing the wmname thing.

MacOS

1. If you have downloaded josm-latest.jar you can start JOSM by clicking on the josm-latest.jar file in the MacOS Finder (you might get the warning that you are about to open a file from the internet - just accept).

This way to start JOSM should be sufficient in most cases.

2. If you are running Mountain Lion, you will need to temporarily disable Gatekeeper. Otherwise, you will be unable to open josm and upon launching josm, receive the error message "JOSM.app is damaged and can't be opened. You should move it to the Trash." Disable Gatekeeper by opening System Preferences > Security & Privacy, and setting 'Allow applications downloaded from:' to 'Anywhere'. Once you open the application, you can re-enable gatekeeper, and it appears that JOSM will open again without a problem. See ​this and #7904 for more information.

3. If you get "The Java JAR file could not be launched", chances are you are running Java 6 rather than Java 7. Run from a terminal to check, as nothing appears in the system log.

4. If you need to supply parameters (e.g. -Xmx2048M to run with more Java memory) you can use the MacOS "Terminal":

Start the "Terminal" application (e.g. by typing "Terminal" into the Spotlight search)

• Now you have two options:
  • type in the following command and press "Enter" to start JOSM without any special java options (simply starts up JOSM like under point 1):

    java -jar FOLDER/josm-latest.jar
    

    Whereas "FOLDER" should be replaced by the name of the folder you have josm-latest.jar downloaded to. If you have downloaded it to the standard MacOS "Downloads" Folder it would look like:

    java -jar Downloads/josm-latest.jar
    

  • to use additional java options just add them right after "java"

If you for example have experienced the "Out of memory" warning (e.g. trying to load geo-tagged photos to JOSM) you would start JOSM like this:

java -Xmx512M -jar FOLDER/josm-latest.jar

This would allow JOSM to use up to 512 MB of RAM (memory). The java option "-Xmx512M" set's the maximum Java heap size to 512 MB. You are free to replace -Xmx512M by any number appropriate for your system (e.g. -Xmx2048M or even more).

By the way. To get an overview of all Java start options you can type in:

java -help

4. If you are using the Mac OS X Package and want to alter a startup parameter permanently, then you will need to alter the Info.plist file within the /Applications/JOSM.app/Contents directory. For example, to increase the maximum Java heap size from 512MB to 2048MB, either using the terminal or XCode, in the JVMOptions key alter the entry -Xmx512m to -Xmx2048m.

Getting the Source

JOSM is available under GPL, and so of course you can get the sources and compile, modify or redistribute it by yourself. You can grab the sources via ​subversion

svn co https://josm.openstreetmap.de/svn/trunk josm

Or you can inspect single files over the web frontend at svn (or browser).

Compiling

Using ant

The easiest way to compile JOSM provided Java on your machine is properly set up is to go to the josm directory and type:

ant

That will create a dist/josm-custom.jar file if successful.

Using eclipse

Use eclipse and the provided .project and .classpath file. Just add a new Java Project using the JOSM source folder as existing path.

As of Eclipse 3.5.2 and the latest JOSM (August 10, 2011), you will have problems compiling, due to problems compiling Mappaint MapCSS with a fresh install of Eclipse. First you will need the ​JavaCC ​plugin for Eclipse. To install it in Eclipse, go to Help->New Software... then add the site ​http://eclipse-javacc.sourceforge.net/ as a source, and install the JavaCC Eclipse Plug-in. Then in the Package Explorer, expand org.openstreetmap.josm.gui.mappaint.mapcss, right-click on MapCSSParser.jj, and "Compile with JavaCC". This should put new java files in a package called org.openstreetmap.josm.gui.mappaint.mapcss.parsergen, but if it doesn't, you will have to create the package manually (right-click and create package), then drag the new files into the package you just created (they should be easy to identify based on the light gray text that denotes it was compiled from MapCSSParser.jj). This should resolve any import issues in MapCSSStyleSource.java, and you should now be able to compile JOSM.

If you try to compile the JOSM sources in Eclipse and get errors like "The method marktr(String) is undefined for the type SomeType" look at ​solution suggested at mailing list.

There are also two Videos available at youtube, which show ​how to checkout JOSM into Eclipse and ​how to checkout a JOSM plugin into Eclipse.

Unit Tests

It is most convenient, to run tests from an IDE like Eclipse or Netbeans. There is also an ant task to run all tests (but you cannot rerun individual tests).

All unit tests can be run in headless mode (i.e, without a graphic display), allowing them to be run in continuous integration projects.

Running Test from Command line

You can run tests from the command line, as well. Include all libraries in the class path like this:

export TESTCP=".:test/unit:test/functional:dist/josm-custom.jar:test/lib/fest/fest-assert-1.0.jar:test/lib/fest/MRJToolkitStubs-1.0.jar:test/lib/fest/jcip-annotations-1.0.jar:test/lib/fest/fest-swing-1.1.jar:test/lib/fest/fest-reflect-1.1.jar:test/lib/fest/fest-util-1.0.jar:test/lib/fest/debug-1.0.jar:test/lib/junit/junit-4.11.jar:test/lib/jfcunit.jar:test/lib/unitils-core/ognl-2.6.9.jar:test/lib/unitils-core/commons-lang-2.3.jar:test/lib/unitils-core/unitils-core-3.3.jar:test/lib/unitils-core/commons-logging-1.1.jar:test/lib/unitils-core/commons-collections-3.2.jar"

Then run for example

javac -cp $TESTCP test/unit/org/openstreetmap/josm/data/projection/ProjectionRefTest.java
java -cp $TESTCP org.junit.runner.JUnitCore org.openstreetmap.josm.data.projection.ProjectionRefTest

See also

HowTo JOSM-under-Linux