# OpenMapTiles: turning OpenStreetMap into basemap tiles you can restyle

> An open vector tile schema that turns OpenStreetMap and Natural Earth into styled basemap layers through PostGIS and SQL. It is a data pipeline, not a map viewer, and the trade-off is tile size.

**openmaptiles/openmaptiles** — OpenMapTiles Vector Tile Schema Implementation

- Repository: https://github.com/openmaptiles/openmaptiles
- Website: https://openmaptiles.org
- Stars: 3,202 · Forks: 680
- Language: PLpgSQL
- License: NOASSERTION
- Published: 2026-10-07 · Updated: 2026-10-07 · Language: en
- Canonical page: https://hysenlabs.com/projects/openmaptiles-openmaptiles

## A tile schema, not a map viewer

The first thing to get straight is that OpenMapTiles renders nothing. It is a schema and a build pipeline that produce vector tiles, and something else draws them. The README describes it as an extensible and open tile schema based on OpenStreetMap, used to generate vector tiles for online zoomable maps, aimed at creating beautiful basemaps with general layers containing topographic information.

The word that does the work in that description is general. The README repeats the constraint: the schema should display general topographic content, and if you want a specific theme, create a fork and invite other community members to cooperate on your topic. The reason given is scale. The schema is used in many projects around the world, and the size of the final vector tiles has to be considered in any update. Every feature added to the shared schema is a feature every consumer downloads.

So the deliverable is a directory of layers that a client like Mapbox GL can render with a style you supply separately.

The project sits on top of a sibling repository, `openmaptiles-tools`, which does the heavy lifting of actually creating the tiles. The last push was on 2026-07-29 and the most recent release is V3.16, published on 2025-12-18.

## Fifteen layers, and the ones that cost the most

The schema is a list of documented, self-contained layers: `aeroway`, `boundary`, `building`, `housenumber`, `landcover`, `landuse`, `mountain_peak`, `park`, `place`, `poi`, `transportation`, `transportation_name`, `water`, `water_name` and `waterway`.

The self-contained part is the design rule, and it is what makes the schema extensible. Each layer has its own `mapping.yaml` describing which OSM tags enter it, its own SQL, and its own style snippet, all under `layers/`. Modify one layer and the others do not move.

Which layers are expensive is fairly predictable. `poi` is the layer that fills your tiles, because points of interest are unbounded and a city centre has thousands. `housenumber` is the other one, at high zoom levels where address-level detail is expected. If you are trimming a tileset, those two are where the bytes are. Conversely `mountain_peak`, `water_name` and `aeroway` are comparatively cheap.

Version 3.16 shows the maintainers working on exactly these kinds of trade-offs. It de-duplicates `transportation_name` features and fixes dropped road segments at zoom levels 4 and 5, both of which are size and correctness work on the largest layers in the schema.

## The Docker requirement is not optional

You need Docker to work on OpenMapTiles, at version 1.12.3 or newer, plus Docker Compose at 1.7.1 or newer. There is no local install path, because the pipeline is genuinely containerised: a PostGIS database, an import-data step, and the tools image that does the tile generation.

The clone and build is three commands:

```bash
git clone https://github.com/openmaptiles/openmaptiles.git
cd openmaptiles
# Build the imposm mapping, the tm2source project and collect all SQL scripts
make
```

That `make` assembles the Imposm mapping, the tm2source project, and every layer's SQL into a build directory. It is a compile step for data.

For an interactive look there is a shortcut, and it is the fastest way to understand the project:

```bash
./quickstart.sh <area>
```

With no area given it imports Albania, and `make list-geofabrik` shows what is available. The README also calls out a Windows detail worth knowing before you waste an afternoon: under WSL, use the Linux `/home/user/` directory rather than `/mnt/c`.

## Four import steps, and the order they have to run in

The database starts as a container, and three separate imports populate it.

```bash
make start-db
make import-data
```

`make import-data` brings in external data from OpenStreetMapData, Natural Earth and OSM lake labels. Natural Earth country boundaries matter because they are used in the few lowest zoom levels, which is where real OSM data is thin and the map would otherwise be empty.

Then the OSM extract itself. You put a PBF file in `./data`, or let the Makefile fetch it, and you can pick a source with `download-geofabrik`, `download-bbbike` or `download-osmfr`, or let `download` choose:

```bash
make download area=albania
```

The `area` parameter has a sharp edge. If more than one `data/*.osm.pbf` file exists, every `make` command requires `area=...`, or you export it once. `area=planet` works for the whole dataset and is described as very large.

```bash
make import-osm
make import-wikidata
```

`make import-osm` applies the mapping rules from `build/mapping.yaml`. `make import-wikidata` is the interesting one: for any OSM feature carrying a `Key:wikidata` tag, OpenMapTiles looks up the corresponding Wikidata item and uses its labels for the languages listed in `openmaptiles.yaml`, so a name field arrives in several languages. It queries the Wikidata Query Service for only the IDs already in your database, which keeps the request set proportional to your extract.

## The edit loop has two halves that people mix up

This is the part of the README that saves the most time, because the two kinds of change need different commands.

If you changed a `mapping.yaml` or added OSM tags, you changed what gets imported. The PostgreSQL tables need rebuilding, and new Wikidata records may appear:

```bash
make clean
make
make import-osm
make import-wikidata
```

If you changed layer SQL, you changed what gets selected, so only the SQL import is needed:

```bash
make clean
make
make import-sql
```

Running `import-osm` when you only touched SQL costs you a full reimport of the extract, which on a country extract is minutes and on a planet extract is a different order of magnitude. That asymmetry is the main reason the commands are documented this separately.

The README adds one more rule that is easy to skip: if a change adds a new feature to the tiles, such as new OSM tags, you must also modify the layer style snippet to add a style layer, or the data ships and nothing renders it. Data and style are maintained in the same repository but are separate concerns, and a feature that appears in the tiles without a style entry is the classic confusing outcome of this workflow.

## Configuration, styles, and the licensing question

Configuration lives in `.env` at the repository root, and `docker-compose.yml` reads it through `env_file: .env`. The Compose file also forwards the tuning knobs that decide how much work happens: `DIFF_MODE`, `MIN_ZOOM`, `MAX_ZOOM`, `BBOX` and `MAX_PARALLEL_PSQL`, all overridable from your shell. Two of the comments in that file are practical warnings: Postgres JIT is disabled by default because of slow large MVT query processing, and `shm_size: 512m` is suggested to avoid a `No space left on device` failure during tile generation. The Makefile supports both `docker compose` V2 and `docker-compose` V1, and detects which one you have.

Styles are a separate concern with separate repositories. The README lists OSM OpenMapTiles, OSM Bright, MapTiler Basic, MapTiler 3D, Fiord Color, MapTiler Toner, OSM Liberty, Positron and Dark Matter, and points at Maputnik for building your own GL style. Note the split: this repository produces tiles, and each style repository decides how they look.

On licensing there is an unresolved inconsistency in the repository itself. The license field is reported as NOASSERTION, which means no license was detected, while a `LICENSE.md` file sits at the repository root. Both facts are true and neither settles the other, so if you plan to build on this schema, read `LICENSE.md` yourself rather than inferring terms from the metadata field.

The project has no documentation site in this repository beyond `QUICKSTART.md`, `TESTING.md`, `UPDATE.md`, `BENCHMARKING.md` and `CONTRIBUTING.md`, all of which point back at openmaptiles.org for the schema and docs.

## Conclusion

OpenMapTiles is the right tool when you need a self-hosted basemap you can restyle without a tile vendor contract, particularly for an internal deployment where a general topographic basemap is exactly what you want and the schema is already documented at openmaptiles.org. It is the wrong tool if you need a specific theme baked into the tiles, since the README asks you to fork for that, or if your budget cannot absorb a full planet import and PostGIS to query. Read the README's own warning about tile size before you start, because every layer you add is paid for in bytes on every request. Begin with `./quickstart.sh <area>` on a small extract, then run `make import-data`, `make import-osm` and `make import-wikidata` in that order before touching any layer SQL.

## FAQ

### What is OpenMapTiles and how do I build it?

It is an open vector tile schema based on OpenStreetMap, used to generate vector tiles for zoomable maps. Building requires Docker 1.12.3+ and Docker Compose 1.7.1+, then `git clone`, `cd openmaptiles` and `make` to assemble the Imposm mapping, tm2source project and layer SQL.

### How do I try OpenMapTiles without importing a whole country?

Use `./quickstart.sh <area>`, which downloads and imports a given area automatically, defaulting to Albania when no area is given. `make list-geofabrik` shows the available areas. This is much faster than a planet import.

### What order do the OpenMapTiles import steps run in?

Start with `make start-db`, then `make import-data` for Natural Earth and other external data, `make download area=albania` to fetch an extract, `make import-osm` to load it using the mapping rules, and `make import-wikidata` to pull multilingual labels for features carrying a wikidata tag.

### Do I need make import-osm after changing layer SQL?

No. A layer SQL change needs `make clean`, `make` and `make import-sql`. Reimporting OSM is only required when you change a layer's `mapping.yaml` or add OSM tags, because that changes what enters the database rather than what is selected from it.

## Sources

- [Issues](https://github.com/openmaptiles/openmaptiles/issues)
- [openmaptiles/openmaptiles on GitHub](https://github.com/openmaptiles/openmaptiles)
- [Project website](https://openmaptiles.org)
- [README](https://github.com/openmaptiles/openmaptiles/blob/master/README.md)
- [Releases](https://github.com/openmaptiles/openmaptiles/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/openmaptiles-openmaptiles