From OpenStreetMap Wiki
Jump to: navigation, search
macOS logo

This page give notes for JOSM on macOS (installing and using).

System requirements

JOSM needs Java 8 (newer may work too) since version 10580. See Java Runtime Environment for more Java-related help.

For Java 8 you need at least Mac OS X 10.7.3. For users of older Mac OS versions:

  • Mac OS X 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 X 10.4: (with Java 1.5) you can only run very old versions of JOSM.


  • Download
  • Double click to unzip it to a folder
  • Drag icon to your 'Applications' folder
  • You can safely delete the unzipped folder and remaining files left behind.


Double-click the 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

Updating JOSM

JOSM will nag you to update when new versions become available. To update JOSM...

  • Download the newest
  • Quit from JOSM if it is running
  • Delete from the 'Applications' folder (Note: This does not delete your plugins or settings)
  • Return to your new download, and unzip it.
  • Drag the new 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

Or just get a separate mouse with two buttons and scroll-wheel. It's much better!

More installation notes

'' is an application downloaded from the internet

If you get an error saying "'' is an application downloaded from the internet." you can bypass this by right-clicking on 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.

'' is damaged and can't be opened

If you get an error saying "'' 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

  1. Make sure JOSM isn't open so it can be started using the Terminal application
  2. Open Terminal (from Applications/Utilities/ in Finder)
  3. Change to the directory where josm-latest.jar is... If it's on your desktop, try 'cd Desktop'
  4. 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 OS X 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 MacOS X. 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:

-Xmx512M -XX:MaxPermSize=512M

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

  1. locate JOSM in Applications
  2. Ctrl-Click (Right-Click) the icon and choose Show Package Contents
  3. select Contents
  4. double-click Info.plist, that should open the Property List Editor
  5. expand Java
  6. expand VMOptions
  7. add an item - various ways, e.g. through menu
  8. enter the value, e.g. -Xmx512M -XX:MaxPermSize=512M
  9. save
  10. (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/)

A list of plugins is on the JOSM/Plugins page in this Wiki, and also in the JOSM Wiki.