tilemaker README

The project's README from github.com/systemed/tilemaker. As one markdown file: README.md.

tilemaker

tilemaker creates vector tiles (in Mapbox Vector Tile format) from an .osm.pbf planet extract, as typically downloaded from providers like Geofabrik. It aims to be 'stack-free': you need no database and there is only one executable to install.

Vector tiles are used by many in-browser/app renderers, and can also power server-side raster rendering. They enable on-the-fly style changes and greater interactivity, while imposing less of a storage burden. tilemaker can output them to individual files, or to .mbtiles or .pmtiles tile containers.

See an example of a vector tile map produced by tilemaker at tilemaker.org.

Continuous Integration

Getting Started

We provide a ready-to-use docker image that gets you started without having to compile tilemaker from source:

  1. Go to Geofabrik and download the monaco-latest.osm.pbf snapshot of OpenStreetMap
  2. Run tilemaker on the OpenStreetMap snapshot to generate Protomaps vector tiles (see below)
    docker run -it --rm -v $(pwd):/data ghcr.io/systemed/tilemaker:master /data/monaco-latest.osm.pbf --output /data/monaco-latest.pmtiles
  1. Check out what's in the vector tiles e.g. by using the debug viewer here

To run tilemaker with its default configuration

docker run -it --rm --pull always -v $(pwd):/data \
  ghcr.io/systemed/tilemaker:master \
  /data/monaco-latest.osm.pbf \
  --output /data/monaco-latest.pmtiles

To run tilemaker with a custom configuration using coastlines and landcover you have two options

  1. In the config.json use absolute paths such as /data/coastline/water_polygons.shp or
  2. Set the docker workdir -w /data with relative paths coastline/water_polygons.shp (see below)
docker run -it --rm --pull always -v $(pwd):/data -w /data \
  ghcr.io/systemed/tilemaker:master \
  /data/monaco-latest.osm.pbf \
  --output /data/monaco-latest.pmtiles \
  --config /data/config-coastline.json \
  --process /data/process-coastline.lua

Installing

tilemaker is written in C++14. The Makefile builds it as C++14 and the cmake build as C++17; writing MapLibre Tiles (MLT) needs a C++20 compiler. The chief dependencies are:

Other third-party code is bundled in the include/ directory.

You can then simply install with:

make
sudo make install

For detailed installation instructions for your operating system, see INSTALL.md.

Out-of-the-box setup

tilemaker comes with configuration files compatible with the popular OpenMapTiles schema, and a demonstration map server. You'll run tilemaker to make vector tiles from your .osm.pbf source data. To create the tiles, run this from the tilemaker directory:

tilemaker /path/to/your/input.osm.pbf /path/to/your/output.mbtiles

tilemaker keeps everything in RAM by default. To process large areas without running out of memory, tell it to use temporary storage on SSD:

tilemaker /path/to/your/input.osm.pbf /path/to/your/output.mbtiles --store /path/to/your/ssd

Then, to serve your tiles using the demonstration server:

cd server
tilemaker-server /path/to/your/output.mbtiles

You can now navigate to http://localhost:8080/ and see your map!

Coastline and Landcover

To include sea tiles and small-scale landcover, run

./get-coastline.sh
./get-landcover.sh

This will download coastline and landcover data; you will need around 2GB disk space.

Have a look at the coastline and landcover example in the resources/ directory.

Your own configuration

Vector tiles contain (generally thematic) 'layers'. For example, your tiles might contain river, cycleway and railway layers. It's up to you what OSM data goes into each layer. You configure this in tilemaker with two files:

You can read more about these in CONFIGURATION.md.

The JSON configuration and Lua processing files are specified with --config and --process respectively. Defaults are config.json and process.lua in the current directory. If there is no config.json and process.lua in the current directory, and you do not specify --config and --process, an error will result.

Read about tilemaker's runtime options in RUNNING.md.

You might also find these resources helpful:

Why tilemaker?

You might use tilemaker if:

But don't use tilemaker if:

Contributing

Bug reports, suggestions and (especially!) pull requests are very welcome on the Github issue tracker. Please check the tracker to see if your issue is already known, and be nice. For questions, please use IRC (irc.oftc.net or https://irc.osm.org, channel #osm-dev) and https://community.osm.org.

Formatting: braces and indents as shown, hard tabs (4sp). (Yes, I know.) Please be conservative about adding dependencies or increasing the memory requirement.

The Makefile does not currently pick up changes to header files (.h). If you change these, you may need to run make clean before building with make and sudo make install.

tilemaker is maintained by Richard Fairhurst and supported by many contributors. We particularly celebrate the invaluable contributions of Wouter van Kleunen, who passed away in 2022.

Copyright tilemaker contributors, 2015-2025.

The tilemaker code is licensed as FTWPL; you may do anything you like with this code and there is no warranty.

Licenses of third-party libraries:

tilemaker (systemed/tilemaker)

Searching Database…

What is this?tilemaker is a command-line tool that turns an OpenStreetMap .osm.pbf extract into Mapbox Vector Tiles, without needing a database.
Is it a library or a standalone tool?It is a standalone tool: you run one executable on an input file and get tiles as output, with no database or server stack to set up.
How do I get it running?The quickest route is the ready-made Docker image. Otherwise run make and sudo make install, and see INSTALL.md for OS-specific steps. Then run tilemaker on your .osm.pbf file to produce .mbtiles.
What do I need installed first?A C++14-capable compiler, Boost (1.66 or newer), Lua 5.1 or LuaJIT, sqlite3, shapelib and rapidjson. The Docker image skips all of this, and MapLibre Tiles output needs a C++20 compiler.
Any gotchas with large areas?tilemaker keeps everything in RAM by default, so for large areas point it at an SSD with --store to avoid running out of memory.
Should I use it instead of hosted tiles?Use it if you want to build your own tiles without a third-party contract. Skip it if you want someone else to host the tiles or need continuous updates from the latest OSM data.
Can I make tiles for offline use?Yes, the README names ready-to-go offline tiles as a reason to pick tilemaker.
Is it free to use?Yes. The tilemaker code is under the FTWPL, which lets you do anything with it and comes with no warranty. Bundled third-party libraries have their own permissive licences.
What do the output files look like and where can I use them?Output goes to individual files or to .mbtiles or .pmtiles containers. The tiles can be rendered in browsers and apps, or server-side for raster images.
Why build it instead of using a database-backed stack?It aims to be 'stack-free': you need no database, and there is only one executable to install.
How do I control which map features end up in the tiles?You write a JSON config listing the layers and zoom levels, plus a Lua script that assigns OSM objects to layers based on their tags.
Can I preview the tiles I generated?Yes. The repo includes a demonstration map server in the server/ directory (tilemaker-server) that serves your output file.
Creator
systemed
Size
42.9 MB
Stars
1.9K
Age
11y
Commits · 90 Days