Valhalla: a tiled OpenStreetMap routing engine in C++

What Valhalla solves that a plain shortest-path library does not

Valhalla is an open source routing engine and accompanying libraries for use with OpenStreetMap data. The problem it addresses is not pathfinding in the abstract. It is the whole chain from a raw OSM extract to a service that answers a route request, an isochrone, a time-and-distance matrix, a map match or a travelling salesman tour. The README lists those as first-class outputs rather than add-ons.

The audience is narrower than the description suggests. This is for teams that can host their own data pipeline: you need an OSM extract, disk space for graph tiles, and someone who understands why costing profiles behave the way they do. If you only need to draw a line between two points once, the public demo server at valhalla.openstreetmap.de covers that. If you need to route millions of requests on your own hardware, or route on a graph you control, the engine is the point.

The licence matters here. The README states that Valhalla and all projects under the Valhalla organization use the MIT License. That is a permissive position compared with routing stacks tied to copyleft terms, and it is the reason the project can be embedded in mobile, web or desktop products. The OpenStreetMap data in ./test/data is separately licensed under ODbL and copyrighted by OSM contributors, which is a data question, not a code question.

Tiled graphs, pluggable costing and the module split

The README names a tiled hierarchical data structure as a differentiator, and the reasoning it gives is concrete: a small memory footprint on memory-constrained devices, offline routing, regional extracts and partial updates. That is a data-layout decision with consequences. You do not load a planet graph into RAM. You build tiles once and query them.

The repository splits responsibilities across modules, and the naming is worth knowing because it tells you where a problem lives. Midgard holds basic geographic and geometric algorithms. Baldr holds the base data structures for accessing and caching tiled route data. Sif handles costing of graph nodes and edges, and the README says its output feeds loki and thor. Skadi is the elevation library and service, usable as input to mjolnir or standalone. Mjolnir is the set of tools that turn open data into Valhalla graph tiles. Loki searches graph tiles and correlates input locations to an edge.

Costing is dynamic and runtime, done through a plugin architecture. In practice that means alternate route generation is a configuration exercise rather than a fork, which is the strongest argument for Valhalla over a fixed-profile engine. The trade-off is that a plugin interface is also an interface you can get wrong, and the README does not document rollback or versioning of custom costing plugins.

Multi-modal and time-based routing are listed as features: mixing auto, pedestrian, bike and public transportation in one route, or setting an arrival time. Transit support brings its own tooling, visible in the pyproject.toml script list as valhalla_ingest_transit and valhalla_convert_transit. Those two steps are separate from tile building, and teams that skip them should expect no transit results rather than a clear error.

Installing Valhalla and running a first route

The repository builds with CMake; vcpkg.json and vcpkg-configuration.json at the top level indicate the dependency route the project expects. The README does not give a step-by-step install for every platform, so treat the project's own documentation site as the source for build flags rather than guessing at them.

The Python bindings are the shortest path to a first result. pyproject.toml declares the distribution as pyvalhalla, described as high-level bindings to the Valhalla C++ library, requires-python >=3.9.0, and licensed MIT. The wheel exposes console scripts, and that list is the most useful thing in the file.

[project.scripts]
valhalla_build_config = "valhalla.valhalla_build_config:main"
valhalla_build_elevation = "valhalla.valhalla_build_elevation:main"
valhalla_build_extract = "valhalla.valhalla_build_extract:main"
valhalla_service = "valhalla._scripts:run"
valhalla_build_tiles = "valhalla._scripts:run"
valhalla_build_admins = "valhalla._scripts:run"
valhalla_add_predicted_traffic = "valhalla._scripts:run"
valhalla_add_landmarks = "valhalla._scripts:run"
valhalla_ingest_transit = "valhalla._scripts:run"
valhalla_convert_transit = "valhalla._scripts:run"

That block is the declared entry point list, so it tells you which build tools you can expect to call. It does not tell you the flags each one takes. The README does not document the flag set for valhalla_build_tiles, so confirm against the documentation before running it on a large extract. Expect the tile build to be the slow, disk-hungry step and the query to be fast.

Once tiles exist, valhalla_service serves them and the HTTP API answers requests. The demo server exposes the same API shape on a different subdomain, for example https://valhalla1.openstreetmap.de/isochrone, which is a useful way to see a response body before your own graph is ready. If you publish an app that calls the public demo server, the README asks you to announce it in GitHub Discussions and send an identifying header such as X-Client-Id: newroutingapp.io. That request is a fair-usage convention, not a guarantee of capacity.

Windows, transit and the limits the README admits

The platform section is unusually blunt. Valhalla is fully functional on many Linux and Mac OS distributions and is used on iOS and Android devices. For Windows, the README states that not all functionality is fully supported yet. Building the library works, along with TOOLS, DATA_TOOLS and PYTHON_BINDINGS. The Python bindings need a full development Python distribution in the PATH.

Read that as a boundary, not a bug. If your production target is Windows, the routing service itself is not in the supported list, and the README does not say when it will be. Linux or macOS is the realistic deployment target.

The public demo server is the second boundary. It is hosted by FOSSGIS e.V. with a full planet graph and an open-source web app, and usage follows the same fair-usage policy as the OSRM and Nominatim demo servers, somewhat enforced by rate limits. Nothing in the README describes an SLA, a quota you can buy, or a support channel. Building a product on the demo endpoint is a misuse of it.

A third limit is documentation depth around operations. The README does not document rollback, does not describe how to update a tile set incrementally despite listing partial updates as a design goal, and does not cover custom costing plugin versioning. The repository does carry SECURITY.md, CONTRIBUTING.md and a CHANGELOG.md, so the process exists, but operational runbooks are not in the README.

Valhalla compared with OSRM and GraphHopper

The honest comparison is with OSRM and GraphHopper, both of which also route on OpenStreetMap data.

OSRM is the closest in spirit: OpenStreetMap-only, C++, and built around a preprocessed graph served over HTTP. The difference in approach is what you can change at query time. Valhalla's README describes dynamic, runtime costing of edges and vertices via a plugin architecture, and multi-modal routes that mix auto, pedestrian, bike and public transportation with a time constraint. OSRM's model is a prepared profile per instance. If you need one profile and the fastest possible response, that model is simpler to operate. If you need several costing behaviours and multi-modal routes from one graph, Valhalla's plugin layer is the reason to pick it.

GraphHopper is Java, and its core is a routing library you embed rather than a tile-building pipeline you run. That is a different deployment shape: a JVM service against a native binary. Valhalla's C++ core is what the README points to for cross-compilation onto offline portable devices, which is a stated goal rather than a side effect.

The shared cost across all three is the same: you own the data pipeline. None of them removes the tile build, the extract refresh, or the disk budget. Valhalla's tile hierarchy is aimed at keeping memory small on constrained devices, which is a real difference for embedded use, and irrelevant if you are renting a large instance anyway.

Maintenance, releases and what the licence does not cover

The repository is not archived, and the last push was on 2026-09-21. Recent releases are 3.9.0 on 2026-09-19, 3.8.3 on 2026-07-25 and 3.8.2 on 2026-07-08. The cadence is steady: a minor release followed by patch releases roughly weeks apart. CHANGELOG.md and NEWS sit at the top level, so upgrade notes have a home.

Upgrade cost has two parts, and only one of them is the code. Rebuilding the library or reinstalling pyvalhalla is the easy half. The expensive half is the graph: a new release can change tile formats or costing behaviour, and the README does not document a rollback path for tiles. Budget for keeping the previous tile set until the new one is verified.

The project also publishes explicit rules for AI-assisted contributions. Contributors must understand every line, PR descriptions must be written by a human, contrived AI logic with generic variable names should be rewritten, and non-obvious changes should be commented inline. The README says PRs ignoring these guidelines might be closed without notice and the worst offenders might be blocked from the organization. If your team contributes upstream, that policy is part of the integration cost.

On licensing, the README states MIT for the code. That is permissive, and it says nothing about the data you feed in. OpenStreetMap extracts carry ODbL obligations and OSM contributor copyright, and the README points to its data-sources documentation for the sources Valhalla commonly uses. Review those terms for your own use case; this is a description of what the repository says, not legal advice.

Editorial conclusion

Adopt Valhalla if you need a self-hosted OpenStreetMap routing engine with tiled graphs, plugin-based costing and multi-modal routes, and you are willing to run a tile build pipeline. Do not adopt it if you want a hosted API with an SLA, or if Windows is your only target, since the README states that not all functionality is fully supported there. Before committing, build tiles from a small regional extract, check which scripts the pyvalhalla wheel actually exposes, and decide how you will regenerate tiles when your extract changes.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. valhalla/valhalla on GitHub