Welcome to the JOSM online help system

This help can be corrected at
Some information might be outdated, because JOSM is constantly enhanced with more features and tools. Recently implemented features may miss good illustrations, animations, examples and text explanation. Please help improving by adding them or your personal tips and experience - this is a wiki!

Getting Started

Your first edits with JOSM

  • Introduction to JOSM - briefly covers downloading data, enabling and aligning imagery, main menu items, presets, validation, change-set comments and upload dialogue
  • Migration assist from iD, Potlatch2? or Vespucci? - only if you have difficulties or questions related to respective editor "I'm used to do (function) in (an editor) but what should I do in JOSM?"

OSM-wiki resources


OSM data model


Changesets exists for every of your "edit". They simply group data creations, modifications and deletions - with additional properties comment, created_by, imagery_used and several others (this information stored as simple tags). Similar to other wiki software, one changeset can affect one object (a single character edit in the text), but may contain big changes (removals of paragraphs, partial or complete rewrite of the text) with the only difference that geo information is edited instead of text. Investigating history of one character is equally hard to comparing text at given point in time. Since complete "text" in OSM is 30-600GB big therefore users speak of history within several changesets and not about complete history every time.

Upload changeset dialog - explains why you create a changeset and low level details about protocol that uploads data to the OSM server

JOSM concepts

Workflow examples

JOSM tools (incomplete reference)

List below contains mosty/only unreplaceable tools with preference to core JOSM tools. "Incomplete" should be stated explicitly to avoid misunderstandings from any part.

Search among all JOSM tools and menu items - Ctrl+Spacebar

Basic shape of objects


Selection (or list of currently selected objects) is preciesly described in Help/Dialog/SelectionList#Selection (because it is visible from this dialogue), it can be modified with following tools (incomplete list):


Tags of currently selected objects displayed in Tags/Memberships Dialog.

Topology tools and changes

  • Merge (M) two or more points
  • UnGlue (G, opposite of above) explode single point into multiple
  • Join point into a way segment (N)
  • [Help/Action/DisconnectNodeWay DisconnectNodeWay] (Alt+J, opposite of above) disconnect a node from a way segment
  • [Help/Action/AddIntersections AddIntersections] (Shift+I) (from Help/Plugin/UtilsPlugin2) - will create nodes at places where current selections intersects (or self intersects)
  • [Help/Action/SplitObject Split geometry by selected line] (Alt+X) (from Help/Plugin/UtilsPlugin2)
  • Split way (P) - split way by a node
  • Combine Way (С) - combine several selected ways in one
  • Join overlapping areas (Shift+J)
  • ContourMerge mode can used to glue complex parts that would require too many Merges otherwise; it could also used to partially or full replace geometry of one object with partial or a complete geometry of other object

Geometry tools

Precision in angles

  • Anglesnapping (A, twice) will ease drawing way segments in 30°, 45°, 60° and 90° degrees
  • Extrude (X, with modifiers) tool will ease drawing of strictly perpendicular segments


  • Align in line (L) will align selected nodes into a line
  • Distribute (Shift+B) as above, but also place them at equal distances
  • Parallel (Shift+P), draw lines and curves parallel to each other, draw nested infrastructure quickly
  • "Copy" objects at precise anchor points from commandline
  • "Move" objects at custom vector from commandline
  • Align selected nodes in circle (O)

Viewport control

JOSM interface

JOSM interface overview

Interface terminology (make sure to study bolded items first): Note: Together, 3 and 4 may contain too many items to display at once, use mouse scroll wheel in this case.

1. Main menu

2. Main toolbar

3. JOSM modes

4. toggles used to control on/off state of Windows

5. Status bar

6. Slider and scaler

7. Windows (or dialogs)
Layer List
Relations List
• (others)

8. Main editing window

9. Details about current mode

JOSM starting screen

  1. In JOSM, Help/Downloading data step performed first. For example, use simple Download menu
  2. Additional and more complex tools may be activated with Expert mode (also, pay attention to the left side of the screen)

JOSM interface complete reference

JOSM interface - complete reference. Pay attention, that menu pages at this wiki are very deep, just couple of examples below:

JOSM interface customization

See Help/JOSM interface customization for details.

Last modified 6 days ago Last modified on 2016-05-21T07:16:34+02:00

Attachments (8)

Download all attachments as: .zip