JOSM/Mac

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

System requirements

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.
At this moment, the compiled JOSM version is not working with open JDK versions. It will give an "JRE Load Error". This will be fixed (see https://josm.openstreetmap.de/ticket/18319#comment:40)

See Java Runtime Environment for more Java-related help.

Installation

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.

Start

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

Updating JOSM

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 ←

Apple Magic Mouse/Magic Trackpad

Shortcuts

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.

Another suggestion is to use a non-Magic Mouse or Trackpad, which does have a hardware scroll wheel and has been reported generally to 'work better'.

Zoom is too sensitive

"Zoom being too sensitive" (meaning you zoom in or out without meaning to, or way too quickly, when the scroll function on a Magic Mouse or Magic Trackpad is activated) is a long-standing problem. This is a multi-faceted problem and there isn't a simple straightforward fix, depending on your individual usage. Things you may want to try:

Slow the scrolling speed used by the OS
- macOS 10.13 (High Sierra)
  - System Preferences > Accessibility > Mouse & Trackpad > (Mouse) or (Trackpad) Options > Scrolling speed
Disable inertial scrolling (this may slow down scrolling when you do activate it)
- macOS 10.13 (High Sierra)
  - System Preferences > Accessibility > Mouse & Trackpad > (Mouse) or (Trackpad) Options > [x] Scrolling (without inertia)
Disabling scrolling entirely, meaning zoom-by-scroll is disabled and you will need to scroll using JOSM keyboard shortcuts or the zoom bug in the corner of the JOSM viewport:
- macOS 10.13 (High Sierra)
  - System Preferences > Accessibility > Mouse & Trackpad > (Mouse) or (Trackpad) Options > [ ] Scrolling ~~(with or without inertia)~~
Use a different (non-Apple) mouse entirely, with a separate scroll wheel as part of its hardware

The most probable "correct" method of this being fixed lies in a JOSM Javascript library dependency called Leaflet. There is a long-standing open bug discussing the problem and possible solutions at Leaflet GitHub Issue #4410.

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 Preferences > Security, and setting 'Allow applications downloaded from:' to 'Anywhere'. See this help question for more.

On macOS Catalina, you may have to remove JOSM.app from quarantine (see this help question):

sudo xattr -rd com.apple.quarantine /Applications/JOSM.app

Memory

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: Supplement JAVA with parameters

Select the Apple square gear (system setting)
Press the Java button (bottom left) with the mouse
In the Java Control Panel, open the JAVA tab
Click "VIEW" and paste the following line in in the "Runtime parameters" field.

-Xmx512M -XX:MaxPermSize=512M

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:

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

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
save
(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 quite 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 in the JOSM Wiki.