headwaymaps

headway: Run a Self-Hosted OpenStreetMap Stack

Headway bundles a map frontend, basemap, geocoder and routing engine into a self-hostable OpenStreetMap stack. Use it to serve maps, search and driving, cycling or walking directions for a chosen area using your own location data.

View on GitHub Compare
Stars
3k
Forks
78
Stars, last 30 days
+13

Our take

Health score

47/100

How it is scored
Activity
52
Community
43
Issues
21
Pull requests
71

+13 stars in the last 30 days

Project history

Daily GitHub snapshots since Oct 7, 2026. History covers stars and forks; health signals are not tracked historically.

Selected snapshot

Stars

3,020

Forks

85

Change since Nov 16, 2026: 0 stars·0 forks

Overview

Headway packages the main parts of a maps service into a stack you can run yourself: a frontend, basemap, geocoder and routing engine. It lets individuals and organizations work with OpenStreetMap data on their own infrastructure instead of relying on a hosted maps provider.

Choose from more than 200 predefined cities or supply an OpenStreetMap extract for a custom area. The stack can display the map, search for places and addresses, and provide directions within the selected extract.

Key Features

  • Self-hosted maps stack powered by OpenStreetMap data.
  • Map frontend and basemap for viewing the selected area.
  • Search for points of interest and addresses in an extract.
  • Routing for driving, cycling and walking.
  • Coverage from a predefined city to a custom area, including larger regions.
  • Data preparation and server operation can be handled on separate machines with different resource needs.

Use Cases

  • A privacy-conscious individual can run maps and place search on their own machine rather than depend on a hosted service.
  • A community or local organization can provide maps and directions for a city using a chosen OpenStreetMap extract.
  • A developer can create a self-hosted base for applications that need geocoding or routing over a specific region.
  • An organization with its own location data can operate a maps stack in its own environment and choose the geographic coverage.

Getting Started

Start with the Headway repository and follow BUILD.md for build instructions. The README describes choosing a predefined city or providing an OpenStreetMap extract.

Considerations

  • Transit directions are a work in progress. Current supported modes are driving, cycling and walking.
  • The project reports confirmed operation on amd64 machines running Linux and macOS.
  • Building data requires at least 8 GB of memory, potentially more for larger areas, and 50 GB to 100 GB of disk space during the build. Running the stack has lower requirements, with around 4 GB cited for a medium-sized metro area.
  • You need an OpenStreetMap extract or a selected predefined city, and larger geographic coverage can increase build resource requirements.

Found this useful?

Share it with someone who would like headway.