Every OpenStreetMap contributor starts in iD, the friendly editor in the browser, and iD is enough for a long time. Then a project arrives that iD makes painful: a bus route relation spanning a city, a hundred buildings to trace with identical tags, a validation error you cannot see, a mapping trip beyond internet range. That is the day JOSM enters. JOSM (the Java OpenStreetMap Editor) is the project's desktop power editor, documented on the OSM Wiki as the tool for experienced mappers, and this guide is the honest briefing before you switch: what it does that iD cannot, what the first session involves, and who should stay in the browser happily. If you have not made your first edit yet, start with our guide to adding a place to OpenStreetMap, which teaches iD; this article is the step up after it.
Home / GIS and Open Map Data for Beginners
JOSM: The OpenStreetMap Desktop Editor for Mappers Who Outgrow iD

Photo: Jakub Zerdzicki / Pexels
First JOSM Session: Setup in Order
Check off each step as you finish it. Your progress stays on this page.
0 of 6 complete
0% done
Who JOSM Is For (and Who It Is Not)
JOSM earns its learning curve for mappers who recognize themselves here: you edit relations (routes, boundaries, turn restrictions) and iD's relation handling feels like defusing a bomb through a keyhole; you do bulk or repetitive work, tracing building batches or retagging a whole neighborhood; you map offline, on trains, in the field, in places where the browser editor cannot load; or you want validation that catches your mistakes before the changeset, not after a stranger's note.
It is not for your first ten edits, and it is not required for casual contributions. A café added correctly in iD is worth more than a JOSM install abandoned in week one. The honest framing from the community itself: iD is the default editor for everyone; JOSM is the specialist instrument you adopt when a specific pain sends you looking. Let the pain choose the timing and the curve feels shorter.
The First Session, in Order
- Install. JOSM is a free Java desktop application for Windows, macOS, and Linux, downloaded from josm.openstreetmap.de. Install it, launch it, and let it connect your OSM account when it offers the OAuth sign in; that handshake is what lets your edits upload under your name.
- Download a small area. Use the download button and pull a neighborhood you know well, smaller than your ambition. JOSM works on a local copy of the data, which is the root of both its power and its one danger, stale data, addressed below.
- Turn on imagery. The Imagery menu offers the same aerial layers you know from iD. Align it, check its offset against GPS traces if your area needs it, and only then draw.
- Learn five shortcuts, not two hundred. JOSM is famous for its keyboard depth, with more than 200 shortcuts documented, but a first session needs a handful: draw (A), select (S), the building tool if you install it, undo, and upload. The rest accrete over months, each one adopted when a repeated mouse trip annoys you into learning it.
- Validate and upload. Run the validator (Shift+V in many setups) before uploading, read what it flags, fix what is yours, and upload with a real changeset comment. That loop, validate then upload, is the JOSM habit that most improves the map per hour of your time.

The Features That Justify the Climb
Relations without fear. JOSM's relation editor lists members in order, shows gaps in a route as breaks in a line, and lets you sort, reverse, and repair with the geometry visible. For route and boundary work this alone repays the install.
The validator. Before upload, JOSM checks your downloaded area for crossing ways, unconnected roads, duplicate points, tagging contradictions, and hundreds of other patterns from its rule set, and increasingly from community rules you can add. Catching your own errors pre upload is the single biggest quality jump the tool offers.
Offline by design. Because JOSM downloads data and works locally, a laptop loaded with areas and imagery caches can map through a flight, a field trip, or an outage, uploading when connection returns. iD cannot leave the browser's connection behind; JOSM was built assuming it would.
Plugins, more than 100 of them. The plugin ecosystem extends the editor in every direction: the buildings tool that draws a house in two clicks, conflation tools for merging imports, scripting, specialized imagery and data sources. Install plugins the way you learn shortcuts: one at a time, when a job demands it, from Preferences, Plugins.
Filters and search. JOSM can filter the downloaded data by any tag expression, dimming everything except, say, buildings without addresses, so a systematic cleanup becomes a visible checklist. Combined with its search, which speaks the same query dialect as the data itself, large area maintenance stops being scrolling and becomes querying.
The One Danger: Stale Data
JOSM's local copy is a snapshot. If you download an area on Monday and upload on Friday, other mappers may have edited the same streets in between, and JOSM will surface conflicts on upload: your version versus the server's version of the same objects. The defenses are habits, not settings: download fresh before each session, keep sessions short, update the data before uploading after any long edit, and resolve conflicts by reading them rather than by always preferring your side. Most conflicts are two people improving the same corner; the merge tools exist so both improvements survive. Respect the snapshot model and it never bites; forget it for a week long edit and it will teach you once, thoroughly.
Staying Bilingual
Graduating to JOSM does not mean abandoning iD. Many experienced mappers keep both: iD for a quick fix spotted while browsing, JOSM for sessions, projects, and relations. The map does not care which editor a good edit came from. What changes with JOSM is the scale of what you can attempt and the certainty the validator gives you before you commit it. That, plus the offline freedom, is the whole case, and for the mappers it fits, it is more than enough. The wider toolkit around editing, including querying the data you improve, is covered in our guide to Overpass Turbo, which pairs with JOSM the way a question pairs with an answer.
Imagery, Offsets, and GPS Traces
Power editing stands or falls on alignment, and JOSM treats it as a first class problem. Aerial imagery is not always registered perfectly to the ground; in some areas it sits a few meters off, and tracing it faithfully draws a neighborhood faithfully wrong. JOSM's answer is layered: public GPS traces uploaded by mappers show as a faint rain of points over the imagery, dense along roads, and where the traces and the imagery disagree, the traces are usually telling the truth about the road's centerline. The imagery offset controls let you shift the layer to agree, and an offset database remembers known local offsets so a region's correction is shared rather than rediscovered by every mapper alone. The working rule: before a serious tracing session in a new area, compare imagery against traces on a few main roads, set the offset once, and only then draw. It is a five minute ritual that iD's simpler model hides from you, and it is one of the clearest examples of what "power editor" actually buys: not more buttons, but control over the assumptions the simple editor makes silently on your behalf.
Presets: Tagging at Speed Without Memorizing the Wiki
The other quiet accelerator is the preset system. Selecting a feature and opening a preset (a highway, a shop, a power line, hundreds exist) presents a structured form: the fields that feature type is supposed to carry, with dropdowns for the standard values. Presets convert tagging from a memory test into a form filling exercise, which is faster and, more importantly, more consistent: the form reminds you that a bench can have a backrest field and a café an outdoor seating field, the long tail of detail that distinguishes a rich map from a sketched one. Combined with JOSM's ability to copy tags from a selected exemplar onto a row of similar features, presets are how a mapper tags two hundred buildings in an evening without inventing a personal dialect of the tagging scheme as they go. The map's consistency across millions of contributors is a social achievement; presets are one of the tools that make it mechanically possible.
Relations, Without the Fear
The topic that frightens new JOSM users most deserves one calm paragraph. A relation is a list of members, ways and nodes, that together form one thing: a bus route made of forty street segments, a boundary made of a dozen border ways, a river with its banks. iD lets you touch relations only through simplified dialogs; JOSM shows you the machinery, a dedicated relation editor listing members in order, with tools to sort, connect, and repair them. You do not need it in your first month, and simple feature editing never requires opening it. But the day a route relation breaks or a multipolygon renders wrong, JOSM is where the fix happens, and the editor's plainness is the point: relations stop being magic and become lists, and lists can be read, checked, and repaired by anyone patient. That demystification, more than any single feature, is the graduation JOSM offers.
The Honest Summary
JOSM is not better than iD in the way a newer phone is better than an older one. It is better the way a workshop is better than a kitchen drawer: more capability, more responsibility, everything within reach once you know where it hangs. Learn it when the browser editor starts costing you time or refusing your ambitions, keep iD for the quick fixes it does beautifully, and let the work choose the tool each day. The map does not care which editor drew it. It cares that the geometry is true, the tags are standard, and the changeset says what you did, and a mapper who can work in both editors can deliver that on any computer, in any country, with or without a connection.
Related Guides
Readers working through this topic usually need its closest companions too. These GIS and open map data guides cover the neighboring ground:
- How to Use OpenStreetMap in Python: OSMnx, Overpass, and Nominatim With Real Code: Python is where OpenStreetMap stops being a map you look at and becomes data you compute with.
- How to Use OpenStreetMap Offline: Apps, Extracts, and Field Editing Without a Signal: OpenStreetMap may be the most offline friendly map data on Earth, because the whole database can live on your phone.
- The Humanitarian OpenStreetMap Team: How HOT Turns Volunteers Into Crisis Maps: When an earthquake or flood hits a place the maps forgot, the Humanitarian OpenStreetMap Team (HOT) organizes thousands of volunteers to map it...
Frequently Asked Questions
Is JOSM better than iD for OpenStreetMap editing?
For complex work, yes; for simple work, they are equal because the edit is the same. JOSM is stronger at relations, validation before upload, offline editing, bulk work, and filtering large areas. iD is faster to start, needs no install, and handles everyday additions perfectly well. Most experienced mappers use JOSM for projects and iD for quick fixes.
Is JOSM free and what do I need to run it?
JOSM is free and open source, a Java desktop application for Windows, macOS, and Linux, downloaded from josm.openstreetmap.de. You need an OpenStreetMap account to upload, which JOSM connects through a sign in flow on first use. It works offline once data and imagery are downloaded.
What does the JOSM validator do?
It checks your data before upload for errors and suspicious patterns: crossing or unconnected ways, duplicate nodes, broken relations, and tagging contradictions, among many others. Running it before every upload and fixing what it flags in your own edits is the fastest way to raise the quality of your contributions.
Why did I get a conflict when uploading from JOSM?
Because JOSM edits a downloaded snapshot, and someone else changed the same objects on the server while you worked. JOSM detects the overlap and asks you to resolve it. Download fresh data at the start of each session, update before uploading after long edits, and resolve conflicts by merging rather than overwriting, so both sets of improvements survive.
How many shortcuts and plugins does JOSM have?
The OSM documentation counts more than 200 keyboard shortcuts and over 100 plugins. You need neither all at once: learn the handful of shortcuts your editing style uses daily, and install plugins one at a time when a specific job, such as building tracing or import conflation, calls for one.
Photo credits: Jakub Zerdzicki (Pexels); Yan Krukau (Pexels). Photos are served from this site; follow the credit to the library page for the original.