libosmium: a header-only C++ library for OpenStreetMap data

A library you include, not one you link

Libosmium is a fast and flexible C++ library for working with OpenStreetMap data, and the single most important structural fact about it is that it is header only.

The README says it plainly: Osmium is a header-only library, so there is nothing to build for the library itself. You add the include directory to your compiler's search path and you are done. There is no configure step for the library, no shared object to find at runtime, and no version of the library to keep in step with the binary you ship, which removes an entire category of deployment problem from a native tool.

The prerequisites are correspondingly light. You need a C++17 compiler and a standard C++ library, and the library works on Linux, macOS and Windows. The one hard constraint is the architecture: you need a 64-bit system, because 32-bit systems are not supported. For a library dealing with coordinates and large files that is a reasonable restriction, but it does mean the library is not available to an embedded 32-bit target.

The include directory is where everything lives, and the README is explicit that all of Libosmium is in those header files, which are needed for building Osmium applications. So the library is a set of headers you vendor or consume through a package manager, and the directory listing in the repository shows the accompanying parts: a benchmarks/ directory with benchmarks checking different parts of Libosmium, a cmake/ directory with the CMake configuration scripts, a doc/ directory with the configuration for the API reference documentation, an examples/ directory, a test/ directory and an osmium.imp file at the root.

The licence is the Boost Software License, recorded as BSL-1.0, and the library was mainly written and is maintained by Jochen Topf, with the git commit log credited for the other authors. The project page is at osmcode.org/libosmium/.

Dependencies are per feature, and that is a deliberate constraint

The dependency section is short and makes a point that is easy to miss in a library of this size.

Different parts of Libosmium, and the applications built on top of it, need different libraries, and the instruction is that you do not need to install all of them, just those you need for your programs. The details are in the list of dependencies in the manual.

That is a design decision rather than an accident of packaging. A library that pulled in every geospatial dependency would be painful to adopt, would drag a large transitive tree into every project that used it, and would produce build friction on platforms where one of those dependencies is awkward to install. Making the dependencies per feature means the cost of adopting the library is proportional to what you actually use.

The external, header-only libraries that are included in the repository are worth noting, and so is one that is not. gdalcpp is included, which is the C++ wrapper around GDAL and is what gives the library its raster and projection handling. protozero was included in earlier versions of libosmium but is not any more, which is a change that matters for anyone upgrading, because a library that has removed a bundled dependency has usually replaced it with something else or narrowed what it supports.

The example file list in the repository is a better guide to what the library covers than the README, which explicitly defers to the manual for more details than it can provide. There are seventeen example programs, and between them they read and write, count, filter and index.

The reading side has osmium_read, osmium_read_with_progress, osmium_dump_internal and osmium_convert. The counting and analysis side has osmium_count, osmium_amenity_list, osmium_road_length, osmium_tags_filter, osmium_change_tags and osmium_pub_names, which is a good spread of the operations a data pipeline over OSM extracts needs.

The indexing side is the interesting group, with osmium_index_lookup, osmium_location_cache_create and osmium_location_cache_use, which is the location cache that lets you resolve a way or node id into a coordinate. And there are the geometry and diagnostic ones, osmium_area_test, osmium_debug, osmium_filter_discussions, osmium_tiles and osmium_create_pois.

Building the tests without building the library

Because the library itself compiles to nothing, the build instructions are about the parts that do compile, which are the tests and the examples.

The sequence is three commands, and the first two are the ordinary out-of-source CMake arrangement:

    mkdir build
    cd build
    cmake ..
    make

This builds the examples and the tests, and the README then says to call ctest to run the tests. The detail worth pausing on is that the library does not participate in this build at all, so the build is fast and the tests are compiled against your headers directly.

There is a second prerequisite for the full test suite, and it comes as a submodule. To download the osm-testdata submodule you call:

git submodule update --init

That enables additional tests. The distinction matters because the tests that need real data are the ones that check the file format parsers against actual extracts, and skipping them leaves you with a suite that verifies the library compiles and does some checking but not much of what you would want verified.

The repository carries a .clang-tidy configuration and a .codecov.yml, so the project runs static analysis and reports coverage, and there is a NOTES_FOR_DEVELOPERS.md file and a CONTRIBUTING.md for contributors. A CHANGELOG.md is present at the root, which is where the release history is.

The CI badge and the packaging status badge point at a GitHub Actions workflow and at Repology, the service that tracks how many distributions ship a given package. The Repology badge is a small but real signal for a library like this, because it means the package is being carried by distribution repositories rather than existing only as a source checkout, and that in turn is a proxy for whether it is being maintained by people other than its author.

The examples directory has its own CMakeLists.txt and a README, so the examples are a first-class part of the project rather than a set of loose files, and they are compiled by the same build.

Reading the API documentation, which the README defers to

The README is short and it is not trying to be a manual. It links the Libosmium manual for more details than the README can provide, and the manual is where the substantive documentation lives.

The doc/ directory in the repository holds the configuration for the API reference documentation, and the manual has separate sections that the README links to directly. There is a dependencies section, referenced as the list of dependencies, and a building chapter, and a section on running the tests. Each of those is a link to a specific place in the manual rather than a summary here.

That structure tells you something about how the project is maintained. The README handles the questions every user has, which are whether it works on my platform, what do I need to install, and how do I build the tests. Everything else, which for a library this size is a great deal, is in the manual and in the headers themselves.

For a header-only library the headers are the reference documentation in a way they are not for a compiled one. The README says that all of Libosmium is in the include files, and with Doxygen-style comments in the headers, which is the configuration in the doc/ directory, the API reference is generated from the code rather than written separately. That is why a library with one primary maintainer can keep a full reference accurate: there is no second copy to drift.

The release history supports the claim that the project is alive rather than merely present. Version 2.22.0 came out in March 2025, 2.23.0 in January 2026 and 2.23.1 in April 2026, and the last push was on 2026-10-19, so the work is ongoing even where the tagged releases are spaced a few months apart.

The library is used as the foundation for the Osmium tool family, of which the examples in this repository are a part, and Jochen Topf is the main author and maintainer, with the commit log covering everyone else who has contributed.

Editorial conclusion

libosmium suits a developer who has to read, write or index OpenStreetMap data in C++ and wants the file format handling and the spatial index done properly rather than written again, and the header-only design means dropping it into a project is a matter of adding an include path. It does not suit you if you want a managed data structure with no C++ involved, and it does not suit you if you need the whole ecosystem installed, because the dependency list is per feature. Before you start, read the dependencies section of the manual, since the library makes a point of not requiring everything, and note the 64-bit requirement, because 32-bit systems are not supported.

Frequently asked questions

Official sources

1. License: BSL-1.0
2. osmcode/libosmium on GitHub
3. Project website
4. README
5. Releases