osm.el: an OpenStreetMap viewer that lives inside Emacs

A map viewer as an Emacs package

Osm.el is described as a tile-based map viewer with a responsive, movable and zoomable display, and the project title is osm.el, an OpenStreetMap viewer for Emacs. The primary language is Emacs Lisp, the licence is GPL-3.0, and the author is Daniel Mendler, whose name also appears on several other well known Emacs packages.

The approach is worth pausing on, because it is unusual. Rather than embedding a map widget, the package draws the map into an Emacs buffer using the image display facilities, and it drives that display with a prefix key map of its own, osm-prefix-map, which you bind to a key of your choosing. The mouse is supported for dragging, clicking and a menu, and the display is moved in large and small steps with the keyboard.

The feature list in the README covers a wide surface. There is a map scale indicator, distance measurement, a go to coordinate command, search for a location by name, planning of routes by name, and the opening of Geo, Google Maps or OpenStreetMap URLs. Tracks and points of interest can be displayed from GPX or TCX files. Bookmarked positions are shown with pins, and the package comes with a list of multiple preconfigured tile servers.

The audience is Emacs users, and the use case that motivates the design is a researcher, writer or developer whose notes contain places, and who wants a map and a location reference in the same workflow as the text. The links it produces, which is the subject of a later section, are the clearest statement of that intent.

Tiles are fetched in parallel with the curl program

The mechanism is straightforward and worth knowing in detail, because it determines the requirements.

The map can be controlled with the keyboard or with the mouse, and the viewer fetches the map tiles in parallel from tile servers via the curl program. So the package is not self contained in the sense of having its own HTTP client; it shells out to curl, which the configuration section lists as a dependency alongside the Emacs version requirement.

That has an upside and a downside. The upside is that the request path is a well known, well tested program rather than an HTTP layer written in Emacs Lisp, and that anyone with a curl configuration already on their machine inherits it. The downside is that a missing curl, or a curl that cannot reach the tile server, shows up as a blank map rather than as a clear error, and that a corporate proxy configuration has to be right in the environment Emacs inherits.

The rendering side has its own requirements, and the README is precise about them. The package requires Emacs 29, and Emacs must be built with libxml, librsvg, libjpeg, libpng and libwebp support. Those are the libraries used to decode the image formats that tile servers return, and they are the usual reason a build of Emacs on an unusual system will not work with the package.

The data has its own terms, and the README carries the notice: the map data is copyright OpenStreetMap contributors, licensed under the ODbL. The package also has an osm-copyright setting, on by default in the example configuration, which displays the copyright information in the map view.

Installation is package-install, from ELPA or MELPA

Installation is the standard Emacs package route. The README states that the package is available from ELPA or MELPA and can be installed with package-install.

The distribution channels are listed with badges, and there are four of them: ELPA, the GNU Emacs package archive, at elpa.gnu.org; GNU-devel ELPA for development versions; MELPA releases, and MELPA snapshots for the nightly builds. The distinction between releases and snapshots is the one that matters in practice, since a snapshot changes without a version bump and is what a user who wants the newest behaviour should expect to see change under them.

The repository itself is minimal. There is osm.el, a README.org which is the source of the README the documentation is generated from, NEWS.org for the change log, a LICENSE file, an .elpaignore and a .github directory.

That last file, .elpaignore, is a small signal about how the project is packaged. An ELPA package has to exclude files that are not needed at runtime, and maintaining that list is part of releasing to ELPA rather than an afterthought.

The README is written in Org mode markup, with the title, author, export file name and Texinfo directory settings at the top, and it exports to Texinfo. So the documentation is a literate source that is both the repository README and the manual, which is the usual arrangement for an Emacs package that wants to be installable and documentable at the same time.

Configuring the tile server, the zoom level and the home location

The example configuration in the README is a use-package block, and it is the clearest statement of what is configurable.

(use-package osm
  :bind ("C-c m" . osm-prefix-map) ;; Alternatives: `osm-home' or `osm'

  :custom
  ;; Take a look at the customization group `osm' for more options.
  (osm-default-server 'default) ;; Configure the tile server
  (osm-default-zoom 15)         ;; Default zoom level
  (osm-copyright t)             ;; Display the copyright information
  (osm-home (list 0 0 3))       ;; Home, configure `calendar-latitude/longitude' instead

The four settings that matter first are the tile server, the default zoom, whether the copyright notice is drawn, and the home location. The home setting is a list of latitude, longitude and zoom, and the comment points out that the alternative is to configure calendar-latitude and calendar-longitude instead, which ties the map home to the position Emacs already knows about.

The binding is a prefix map rather than a single command, so the map's own commands live under one key. The comment offers two alternatives, osm-home for the map on its own, or osm for the full command set.

For a custom tile server, the configuration comment points at osm-add-server, which takes a name, a group, a description and a URL template with the usual placeholders for zoom, tile coordinates and an API key. The README also points at the OpenStreetMap wiki page on raster tile providers and at the project wiki for more configurations, including aerial and satellite tile servers. The URL template format is the same shape any raster tile provider uses, so a provider that is not in the default list is a few lines of configuration rather than a patch.

Locations as bookmarks, Org links, Geo URLs and Elisp links

This is the part of the package that makes it more than a viewer, and it is the reason to prefer a text based map to a graphical one.

Osm.el registers itself as a handler for map URLs, both Geo URLs and Google Maps, through the browse-url-default-handlers list, so those links open in Emacs directly. On top of that there are several ways to store a location, each with a different prefix key.

Pressing b creates a bookmark of the current location, stored as an ordinary Emacs bookmark in bookmark-alist, and you can jump to it with osm-bookmark-jump or bookmark-jump. Pressing l stores an Org link to the current location, which you can then insert into an Org buffer with C-c C-l. Pressing u saves the Geo URL of the current location into the kill ring, where a Geo URL has the form geo:27.96,86.89;z=13, and C-u u saves an Elisp link instead, of the form (osm 51.49 -0.14 11).

The Elisp link is the interesting one, because it is a plain s-expression. As the README points out, that means it can be used in arbitrary text files and manipulated programmatically, and there is an address form of it too:

  (osm "Tour Eiffel, Av. Gustave Eiffel, Paris") ;; Address link

The Org link format follows the geo URI scheme defined in RFC 5870, and the README recommends binding a command to open Org links with org-open-at-point-global, for example to C-c o.

The practical difference from any graphical map application is that a location here is a string in your notes. It can be diffed, committed, searched and jumped to, and it survives the application that produced it.

Distance measurement, GPX tracks and the search commands

A few of the smaller features are worth describing, because they are the ones that show the package being used for work rather than for looking things up.

The distance measurement utility is the clearest. You place or select a pin by clicking with the left mouse button, then create one or more additional way points by pressing shift and clicking. The length of the track is shown in the echo area, and the way points can be selected and deleted with d or DEL.

The track display comes from files. The package can display tracks and points of interest from GPX or TCX files, which covers both GPS devices and the fitness formats, and it provides commands to open and display them.

For finding places there are two separate things. The package provides commands to search for a location and to plan routes by name, and separately it can open Geo, Google Maps or OpenStreetMap URLs, which is the escape hatch for when a location needs to leave Emacs entirely.

The remaining features are small and complete: a go to coordinate command, a map scale indicator, moving in large and small steps, and mouse support for dragging, clicking and a menu.

The one constraint on all of this is the same as before, that the data comes from tile servers and the routes and searches are performed against those services, so the package is only as good as the server configuration and, in the case of routing and search, as the endpoints the tile provider exposes.

Editorial conclusion

osm.el suits an Emacs user who works with places, routes and tracks in their notes and wants a map without leaving the editor, and it suits anyone who prefers a location as a link in a text file over a pin in a graphical application. It does not suit a team that cannot add an external dependency, since the package calls out to the curl program, and it does not suit a workstation whose Emacs lacks the image libraries the package needs. Check three things before you install it: that your Emacs is 29 or newer and is built with libxml, librsvg, libjpeg, libpng and libwebp support, that curl is on the path, and that your use of map data respects the OpenStreetMap attribution and the ODbL terms, since the README carries the copyright notice for the tiles. The last push to the repository was on 2026-08-11 and the project publishes no GitHub releases.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. minad/osm on GitHub
4. README