- 1 System requirements
- 2 Installation
- 3 Start
- 4 Updating JOSM
- 5 Mac keyboard quirks
- 6 Mac mouse/trackpad quirks
- 7 More installation notes
JOSM requires the Java Runtime Environment to run. Depending on the version of MacOS you are running, there is typically a cap on "the newest version of Java you can run", and therefore, a newest version of JOSM you can run. Generally it's best to run the newest version of the Java Runtime Environment that your system can install.
Compatibility with Java 9 for JOSM was added in version 12712 and may be used with the newest Mac OS versions.
- Mac OS 10.10.X to current: Java 9 is available.
- Newest JOSM version that can be run with Java 9: current
- Mac OS 10.7.3 to current: Java 8 is available. As of JOSM version 13053, Java 8 is still supported.
- Newest JOSM version that can be run with Java 8: current
- Mac OS 10.7 to 10.7.2: Upgrade to at least Mac OS 10.7.3, so you can use Java 8.
- Mac OS 10.5 to 10.6: you are stuck with Apple's version of Java 6. This means the recent versions of JOSM will not run, but you can install an older version: Use JOSM version 7000 for Java 6 (version 7000 is the last release compatible with Java 6).
- Mac OS 10.4: you can only run Java version 1.5. JOSM version 3306 is the newest version that can be run under Java 1.5.
See Java Runtime Environment for more Java-related help.
- Download josm-macosx.zip
- Double click to unzip it to a folder
- Drag JOSM.app icon to your 'Applications' folder
- You can safely delete the unzipped folder and remaining files left behind.
Double-click the JOSM.app icon in Applications folder.
The first time you run it, you'll get a warning about an application from the internet
For quick access every time, add it to your dock at the bottom. Drag the icon and drop it there
JOSM will nag you to update when new versions become available. To update JOSM...
- Download the newest josm-macosx.zip
- Quit from JOSM if it is running
- Delete JOSM.app from the 'Applications' folder (Note: This does not delete your plugins or settings)
- Return to your new download, and unzip it.
- Drag the new JOSM.app icon back to the 'Applications' folder.
When you run it again, you'll get a warning again about an application from the internet. You may also get a message "You updated your JOSM software. To prevent problems the plugins should be updated as well". It's usually best to 'Update plugins'
Mac keyboard quirks
Because of the way standalone Java applications run on mac, and because mac has several extra "control" keyboard buttons, it can be that surprising things happen with keyboard shortcuts, however this has been improved in recent mac packages. Hopefully you can now use ⌘+C and ⌘+V for copying and pasting everything (but if it's not working for you, you might try Ctrl + C and Ctrl + V)
- To 'Delete' elements: fn + 'backspace ←'
Mac mouse/trackpad quirks
- Zooming on a trackpad: do a two-fingered swipe (not pressing)
- Panning on a trackpad: do a two-fingered drag (pressing)
- Zooming using a single-button mouse: You can't! Press + to zoom in.
- Panning using a single-button mouse: Hold the 'Ctrl' key while dragging
- Panning alternative, install the plugin Touchscreenhelper. This plugin lets you pan the map using a standard click and drag. Tap the letter T to get into the drag mode, move around the map, then tap T again to toggle it off.
Or just get a separate mouse with two buttons and scroll-wheel. It's much better!
More installation notes
'JOSM.app' is an application downloaded from the internet
If you get an error saying "'JOSM.app' is an application downloaded from the internet." you can bypass this by right-clicking on JOSM.app and selecting 'open'. You should then see the same message but this time with an option to "Open" regardless. This is only necessary on the first run of JOSM.
'JOSM.app' is damaged and can't be opened
If you get an error saying "'JOSM.app' is damaged and can't be opened. You should move it to the Trash", then you need to temporarily disable gatekeeper, by going to your perferences->security, and setting 'Allow applications downloaded from:' to 'Anywhere'. See this help question for more.
If you need to allocate more memory to JOSM (in order to edit larger files or you get the 'strange things may happen' memory error), try one of the following methods.
Option 1: Using the .jar file directly
- Make sure JOSM isn't open so it can be started using the Terminal application
- Open Terminal (from Applications/Utilities/ in Finder)
- Change to the directory where josm-latest.jar is... If it's on your desktop, try 'cd Desktop'
- 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 Mac OS menu bar, and -Xdock:name="JOSM" -Xdock:icon="logo.png" to give it icon and name.
Option 2: Using Jar Bundler
You can also use the Jar Bundler application, which comes with Mac OS. You'll find it at /Developer/Applications/Java Tools/ or at /Developer/Applications/Utilities/ or at /usr/share/java/Tools/ (OSX 10.6 - Snow Leopard). 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 vm options edit box:
(This 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!, for example). 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.
Option 3: Patching the Property List
If you've installed JOSM through webinstall and have a JOSM already, change the memory settings by these steps:
- locate JOSM in Applications
- Ctrl-Click (Right-Click) the icon and choose Show Package Contents
- select Contents
- double-click Info.plist, that should open the Property List Editor
- expand Java
- expand VMOptions
- add an item - various ways, e.g. through menu
- enter the value, e.g. -Xmx512M -XX:MaxPermSize=512M
- (re-)start JOSM
Manually install JOSM plugins
Usually you don't need to install plugins manually! JOSM provides a plugin manager (under Edit/Preferences/Plugins) that makes it very easy to install plugins.
Plugins are manually installed by saving them in ~/Library/JOSM/plugins (earlier versions placed them in ~/.josm/plugins/)