Author: Matthieu Viry and Timothée Giraud
Date: 2026-02-12

# Installing Valhalla with Docker

#### Matthieu Viry and Timothée Giraud

#### 2026-02-12

## 0.1 Introduction

Valhalla is an open-source routing engine that uses OpenStreetMap data to provide routing services. A demo server that is open to the public and includes a full planet graph is available at https://valhalla.openstreetmap.de.

However, the valhalla documentation states that “usage of the demo server follows the usual fair-usage policy as OSRM & Nominatim demo servers” (source) and that this is enforced by a rate limit of “1 call/user/sec and 100 calls/sec total” (source).

This means that if you want to use Valhalla for a large number of requests, you will need to install it locally or on your own server.

Valhalla is a C++ application that can be compiled on most of modern platform and architectures, but this can be challenging if you’re not familiar with development tools and the command line. The easiest way to install Valhalla is to use Docker, which allows you to run Valhalla in a container without having to install it on your machine.

## 0.2 Prerequisites

To follow this vignette, you need to have Docker installed and running on your machine or server as well as a terminal to run the commands. The commands in this vignette should work on any operating system (Linux, MacOS, Windows).

The installation of Docker is not covered here, but you can find the instructions on the official Docker website: https://docs.docker.com/get-started/get-docker/. To ensure that Docker is installed correctly, you can run the following command in your terminal:

    docker run hello-world

If Docker is installed correctly you should see a message saying “Hello from Docker!”.

## 0.3 Valhalla installation

Official Docker images are provided by Valhalla team. The one named “valhalla-scripted” features many options particularly useful for customizing the Valhalla instance to be created (see its documentation if needed) and it’s therefore the one we use here.

### 0.3.1 Downloading an OSM extract

The first thing you need is an OpenStreetMap file, in osm.pbf format, of the region you want to work on.

You can download an extract of the OSM data from Geofabrik or BBBike. Planet files are available on https://planet.openstreetmap.org/, but they are very large and not recommended for local use (as they would require a lot of memory).

Create a folder in which to store this file, here we’ll call it `routing-valhalla` (use `mkdir routing-valhalla` in your terminal to create it). Then, download the OSM extract and move it to this folder.

### 0.3.2 Running the Docker container

To run the Docker container, you need to run the following command in your terminal (you need to be in the parent folder of the `routing-valhalla` folder you created earlier, or else you will need to adapt the path to the folder):

    docker run -t --name valhalla_server \
        -e build_elevation=True \
        -p 8002:8002 \
        -v $PWD/routing-valhalla:/custom_files \
        ghcr.io/valhalla/valhalla-scripted:latest

Here we are using:

- the `-t` option to run the container in interactive mode,
- the `--name` option to name the container `valhalla_server`,
- the `-p` option to publish the container’s port 8002 to the host’s port 8002,
- the `-v` option to mount the folder we created earlier (`routing-valhalla`) to the `/custom_files` folder in the container,
- `ghcr.io/valhalla/valhalla-scripted:latest` image to run the container.

and more importantly,

- the `-e` option to set the environment variable `build_elevation` to `True`, which builds the elevation data for the region.

Other useful options are listed on the image’s README file.

These include : - `build_elevation` to download and build elevation data (default: `False`), this is particularly useful for bicycle and pedestrian routing, - `build_admins` to build administrative boundaries (default: `True`), this is useful for applying border-crossing penalties, - `build_time_zones` to build timezone data (default: `True`), this is useful for time-dependent routing.

Once the graph is built, you should see a message like this:

    INFO: Found config file. Starting valhalla service!

Note that this message is often followed by a several other messages, such as:

    [INFO] Tile extract successfully loaded with tile count: 166
    [WARN] (stat): /custom_files/traffic.tar No such file or directory
    [WARN] Traffic tile extract could not be loaded

This is normal, as we did not provide traffic data to the container (and as traffic data are loaded when the server is started).

You can now access the Valhalla API at `http://localhost:8002/` (replace `localhost` by the IP address of your server if you are running it on a remote server). Go to `http://localhost:8002/status` in your browser to check that the server is running).

### 0.3.3 Interacting with the container

To stop the container, you can kill the process running in the terminal (using `Ctrl+C`), or you can run the following command in another terminal:

    docker stop valhalla_server

To restart the container, you can run the following command in your terminal:

    docker start valhalla_server

This time the server starts instantly, as the graph has already been built, and the container will run in the background (in detached mode). If needed you can check the logs of the container with:

    docker logs valhalla_server

Finally, to totally get rid of the container and the image, you can run the following commands:

    docker rm valhalla_server
    docker rmi ghcr.io/valhalla/valhalla-scripted:latest

## 0.4 Using Valhalla with R

To use your custom Valhalla instance with R and the `valh` package, you just need to change the `valh.server` option to the url of your server or your machine :

    options(valh.server = "http://localhost:8002/")

You can also set this option in your `.Rprofile` file to make it permanent.

You’re now ready to use `valh` with your own Valhalla installation!