Open-source project
valhalla/valhalla avatar
valhalla/valhalla

Valhalla: an OpenStreetMap routing engine with its own AI contribution rules and timezone database

Open Source Routing Engine for OpenStreetMap

6,461 stars1,033 forksC++NOASSERTION

At a glance

What is it?
A C++ routing engine split into named library modules, a separate Python distribution with ten console scripts, a demo server that asks shipped apps to identify themselves, and a contribution policy that accepts AI written code under four conditions. The details that decide whether you can actually use it.
Who is it for?
Use it if your data is OpenStreetMap and you need more than a turn by turn router, because the isochrone, matrix, elevation, map matching and tour optimization tools are the reason to choose this engine over a simpler one, and the tiled data structure is what lets it run with a small memory footprint or offline on a device. Before you commit, check four things.
Can I use it commercially?
Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly C++, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • valhalla/valhalla6,461 ★ · +216
Star history
Repository2026-09-232026-11-15
valhalla/valhalla6.2k6.5k

216 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

AI written code is accepted under four rules, with teeth

The readme has a section on generative AI usage, and its position is neither a ban nor a free pass. It states that AI usage is accepted, for this project and its related ones, and then sets out four requirements.

First, the human developer has to have understood every line of code written and has to verify that the proposed implementation actually works. Second, the pull request description being written or rewritten by a human is non negotiable. Third, contrived logic produced with generic variable names should be rewritten to match human perception. Fourth, non obvious code changes should be commented inline, and the readme is specific that this belongs in the code rather than in the pull request description.

The consequences are stated as plainly as the rules. The second and third are described as subjective, where the project says it has more patience, and then it says pull requests that ignore the guidelines entirely might be closed without further notice, and that the worst offenders might be blocked from the organization.

That is a workable policy for an open source project because it puts the verification burden where it belongs. Rule one is the one that matters: a contributor who cannot explain a line they submitted has not met the bar, and a reviewer can enforce it without judging anybody's tooling.

The public demo asks shipped apps to identify themselves

A demo server is hosted by the FOSSGIS association and is open to the public. It carries a full planet graph and comes with an open source web front end, at `https://valhalla.openstreetmap.de`, with the HTTP API on a slightly different subdomain, for example `https://valhalla1.openstreetmap.de/isochrone`. The split is stated because the front end and the API are not the same host.

The usage terms follow the fair use policy that the OSRM and Nominatim demo servers use, and the readme says the limits are somewhat enforced through rate limits linked from a discussion thread. So the server is a shared resource under pressure, not infrastructure you can depend on.

What makes this section worth reading is the request aimed at product builders. If you publish an application, mobile, web or desktop, that calls the public demo server, the project asks two things of you: tell them in GitHub Discussions, and include an identifying client header on your requests, with the example given as `X-Client-Id: newroutingapp.io`.

That is a small courtesy with a large practical effect. A server operator looking at a spike in traffic can then tell an application from a script, and can ask the people responsible to stop or to move to their own instance. Applications that skip it are the reason such a note exists.

Two licence files at the root, no assertion in the metadata, ODbL for test data

The readme states that Valhalla and all projects under the organization use the MIT licence, with the text linked at a file named COPYING. The repository root also carries a separate LICENSE.md, and the licence metadata attached to the repository reports no assertion at all, so the identifier you find depends on where you look.

The data is a separate question and the readme separates it properly. The OpenStreetMap data used in the test directory is licensed under ODbL and copyrighted by OSM contributors, and the project points at a documentation page for the licensing and other requirements covering the data sources it uses most often.

That split is the part to hold on to. The code is permissive, the sample data carries an open database licence with its own attribution obligations, and the geographic data you would actually route over carries terms of its own that this repository does not set. There is a documentation page on data sources for that reason.

One more attribution detail sits in the same section: the avatar and logo are credited to a named artist, separate from the code licence, which is the kind of thing that gets missed when a project mixes its own assets with licensed dependencies.

The Python bindings ship as a different distribution with ten commands

The engine is C++, but its Python package is not called the same thing. The project manifest describes a distribution named `pyvalhalla`, described as high-level bindings to the Valhalla C++ library, with a different name from the repository and a different name from the library it wraps.

Its version is declared dynamic rather than written down, which means it is derived from the repository tags at build time by a version control plugin. The build requirements make that explicit: the build backend is scikit-build-core, the binding generator is nanobind, and two version control packages are listed, one of them specifically for the case where the source was exported as an archive rather than cloned. Cmake and ninja are pulled in as build dependencies instead of being assumed present on the machine.

The most surprising line in the manifest is the console script list. Installing this Python package puts ten commands on your path: build config, build elevation, build extract, build tiles, build admins, add predicted traffic, add landmarks, ingest transit, convert transit, and a service runner. That is a tile building pipeline distributed as Python entry points, not a client library.

Typing support is an optional extra rather than part of the install, and it is the only thing that pulls in NumPy, with the version range capped below the next major release.

The documentation toolchain is pinned below 2.0 for a stated reason

The documentation dependencies are the most commented part of the manifest, and the comments explain decisions that would otherwise look arbitrary.

toml
docs = [
    # pin below the 2.0 rewrite: it drops the plugin system and has no migration path
    # consider zensical (still too early in dev)
    "mkdocs>=1.6,<2",
    "mkdocs-material>=9.7,<10",
    "mkdocs-redirects>=1.2,<2",
    "mkdocstrings[python]>=0.27,<2",
]

Four packages, each with an upper bound below its next major version, and the reason given is not caution in general but one specific break: the 2.0 rewrite drops the plugin system and offers no migration path. A second comment records an alternative that was considered and rejected as too early in development.

That is worth reading as a policy rather than a detail. Pinning below a major version is normally the thing maintainers argue about, and here the argument is settled in a comment: the project's documentation depends on plugins, the next major version removes plugins, and there is no upgrade path, so the pin stays.

The typing extra carries a comment too: NumPy is there only for .pyi typing.

Windows covers the library and three named modules, and no more

The platform section is precise about the uneven one. Valhalla is described as fully functional on many Linux and Mac distributions, and as also being used on iOS and Android devices, which is a claim about deployment rather than about a build target.

For Windows, the readme says not all functionality is fully supported yet, and then does something most projects skip: it names exactly what does work. Building the library works flawlessly, as do three application modules. The first is a set of utilities to query and benchmark components. The second builds input data and handles transit. The third is the Python bindings, usable through the Valhalla Python library for routing, isochrones and matrix actions, with the requirement that a full development Python distribution is on the path.

That last clause is a real operational detail rather than a footnote. The Windows story for anyone wanting to script the engine is: install a full development Python distribution, keep it on the path, and accept that the modules outside those three are not covered.

The build status table at the top of the readme shows continuous integration for Linux, macOS and Windows as three separate workflows, plus code coverage and a timezone database job, so Windows is tested rather than ignored.

Nine modules, and the data flow between them is the design

The organization section describes the engine as library modules, each with one function, and the Norse names are memorable in a way that makes the pipeline easy to hold in your head. Midgard holds the basic geographic and geometric algorithms the others build on. Baldr holds the base data structures for accessing and caching tiled route data. Skadi is the elevation data library and service, usable as input to the tile builder or on its own. Mjolnir turns open data into graph tiles. Loki searches those tiles and correlates an input location to an edge or vertex inside a tile. Sif does the costing of graph nodes and edges. Meili does map matching. Thor generates a path through the tile hierarchy. Odin follows Thor.

The edges are the interesting part, because each module names what it feeds. Sif feeds Loki and Thor. Skadi feeds Mjolnir or runs standalone. Loki feeds Thor. Thor feeds Odin.

Read as a chain, that is a complete request lifecycle: a coordinate arrives, Loki finds the entity on the tile, Sif prices the edges, Thor walks a path through the hierarchy, and that path and its attribution feed Odin. Map matching sits beside it through Meili.

The overview also names the six things the project thinks differentiate it, and two of them are architectural rather than functional: a tiled hierarchical data structure for a small memory footprint, offline routing and regional extracts, and a C++ API so the pieces can be cross compiled onto portable offline devices.

Six agent instruction files, a vendored port overlay, and a timezone database of its own

The root of this repository is unusually explicit about what it keeps on hand. There are six assistant instruction files, one each for a general agent format and for five named tools, sitting next to the human contribution guides. There is a clang format config and a clang tidy config, a pre-commit config, a coverage config, and a file for excluding commits from blame.

Dependency management for the C++ side runs through vcpkg, and there are three pieces of it at the root: the manifest, the configuration file, and an overlay directory containing ports the project needs but upstream does not carry. There is also a third party directory and a gitmodules file, so vendored code arrives by two mechanisms at once.

Then there is the timezone database. One of the five build badges in the readme is a job that publishes a timezone database, and a directory named for date and time sits at the root. A routing engine that answers arrive by questions needs a timezone database it controls, because the one on the build machine is not reproducible and because transit timetables are expressed in local time.

The rest of the root is domain specific: a directory for proto definitions, one for translations, one holding a scripting runtime, a pkg-config template for the library, a project metadata file for the OSM ecosystem, a directory of recorded API request fixtures, and one for route scripts.

Editorial conclusion

Use it if your data is OpenStreetMap and you need more than a turn by turn router, because the isochrone, matrix, elevation, map matching and tour optimization tools are the reason to choose this engine over a simpler one, and the tiled data structure is what lets it run with a small memory footprint or offline on a device. Before you commit, check four things. Windows support covers the library and three named application modules, not everything, and the Python bindings need a development Python on your PATH. The public demo server is a testing service with a fair use policy, and if you ship an app that calls it you are asked to announce yourself and send an identifying client header. Licence terms are MIT for the code, but the metadata asserts no licence, two licence files sit at the root, and the test data is ODbL. And if you plan to contribute code written with an assistant, read the four generative AI guidelines first, because the second one is non negotiable. Last push was 2026-11-02 and the newest release is 3.9.1 from 2026-10-06.

Frequently asked questions

What is Valhalla used for?

It is an open source routing engine and set of libraries for use with OpenStreetMap data, written in C++. Beyond turn by turn directions it includes time and distance matrix computation, isochrones, elevation sampling, map matching and tour optimization. The engine is split into library modules, from the geographic algorithms through tile building, costing and path generation.

Does Valhalla accept pull requests written with AI assistance?

Yes, with four requirements: the human developer must have understood every line and verified the implementation works, the pull request description must be written or rewritten by a human, contrived logic with generic variable names should be rewritten, and non obvious changes should be commented inline in the code rather than in the description. The readme says pull requests ignoring the guidelines entirely might be closed without further notice and that the worst offenders might be blocked from the organization.

Can I use the public Valhalla demo server in an app I ship?

The project asks you to do two things rather than forbidding it. The demo is hosted by FOSSGIS with a full planet graph, follows the same fair use policy as the OSRM and Nominatim demo servers with rate limits somewhat enforced, and serves its API on a different subdomain from the web app. If you publish an application that calls it, the readme asks you to announce yourself in GitHub Discussions and to send an identifying X-Client-Id request header.

What licence does Valhalla use?

The readme states that Valhalla and all projects under the organization use the MIT licence, with the text at a file named COPYING, while the root also carries a LICENSE.md and the repository metadata asserts no licence. The OpenStreetMap data in the test directory is separately licensed under ODbL and copyrighted by OSM contributors, and the project documents the requirements for the data sources it uses.

Does Valhalla work on Windows and how do I install the Python package?

Partly on Windows: the readme says building the library works flawlessly, as do the tools and data tools modules and the Python bindings, with the bindings requiring a full development Python distribution on the path, while other functionality is not yet fully supported. The Python bindings are published as a distribution named pyvalhalla, built with scikit-build-core and nanobind, and installing them adds ten tile building and service commands to your path.

Official sources

  1. Issues
  2. Project website
  3. README
  4. Releases
  5. valhalla/valhalla on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/valhalla-valhalla.svg)](https://hysenlabs.com/projects/valhalla-valhalla)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/valhalla-valhalla.svg)](https://hysenlabs.com/projects/valhalla-valhalla)

Was this useful?