Planetiler: building planet-scale vector tiles without a database

One jar, one command, no database

The claim in the README's opening paragraph is specific: build a map of the world in a few hours on a single machine, with no external tools or database. That is the whole pitch, and it is a real difference from the usual tile pipeline, which normally means loading OSM extracts into PostGIS and running a tile generator against it.

The entry point is a downloadable jar and a single command:

wget https://github.com/onthegomap/planetiler/releases/latest/download/planetiler.jar
java -Xmx1g -jar planetiler.jar --download --area=monaco

There is a Docker equivalent that passes the heap size through an environment variable and mounts a data directory:

docker run -e JAVA_TOOL_OPTIONS="-Xmx1g" -v "$(pwd)/data":/data ghcr.io/onthegomap/planetiler:latest --download --area=monaco

The sizing guidance is given up front rather than buried. You need Java 21 or newer, or Docker, at least 1GB of free SSD space plus five to ten times the size of the input PBF file, and at least half as much free RAM as the input PBF. The `-Xmx1g` in the example is tied to that last number, described as a recommendation of 0.5x the input file size so there is room left for memory-mapped files.

That arithmetic is the most useful thing in the README for planning. If your extract is 40GB, you are looking at roughly 20GB of heap and 200 to 400GB of disk, which is a different conversation from a tile server.

Output is MBTiles or PMTiles, served by anything

Planetiler emits Mapbox Vector Tiles and packages them into two container formats: MBTiles, which is SQLite, or PMTiles. The README names the consumers, which tells you the output is not tied to this project. MapLibre renders it in the browser and in native apps, TileServer GL and Martin serve it over HTTP, and PMTiles can be queried directly from the browser with no server at all.

Viewing a result locally takes one npm command for the default format:

npm install -g tileserver-gl-light
tileserver-gl-light data/output.mbtiles

Then localhost:8080. The PMTiles path is different in kind: pass `--output=data/output.pmtiles` and drag the file onto pmtiles.io, which means a single file you can email or put on object storage.

The `--output` flag carries format information in the file extension, so `--output=australia.pmtiles` produces a PMTiles archive of that name. Two operational notes follow from the Docker form of the command: the README advises specifying the full path rather than a bare filename, and in Docker the path needs to be under `/data` so the container can write it.

The common arguments are worth skimming as a set, because they show the intended level of control. `--download` fetches inputs and `--only-download` exits afterwards, which is the flag to use when you want to warm a cache. `--area=monaco` pulls a Geofabrik extract. `--osm-path` points at an existing PBF on disk. `--force` overwrites output, and `--help` lists everything else.

The 1GB download that happens before any tile exists

The Monaco command is small, and the warning directly beneath it explains why it still moves a gigabyte. The OpenMapTiles profile requires about 1GB of data sources, and the README breaks that down into roughly 750MB of ocean polygons and roughly 240MB of Natural Earth Data.

That is worth internalising before planning any pilot. A five minute experiment with a country-sized extract is not a five minute download.

The README then does something thoughtful: it documents smaller substitutes. Both the Java and Docker commands accept `--water-polygons-url` and `--natural-earth-url`, and the example values point at test resources inside the project's own repository. With those in place the download shrinks dramatically, at the cost of not having real ocean or real Natural Earth geometry.

The stated scope of that trick is narrow and clearly marked: you need the full data sources to run anywhere besides Monaco. So it is a development and test convenience, not a way to run a production basemap.

A `NOTICE.md` in the repository root is referenced for the data sources themselves, which is the file to read before redistributing any tiles you build. OpenStreetMap attribution is not optional and the copyright requirements come from the OSM Foundation, not from this tool.

Two ways to define a map: YAML profiles and Java

Customisation is the part that determines whether this is a tool you can actually use for your own layer. The README presents two paths and is direct about which is which: YAML configuration for simple or moderately complex maps, prototyping, and people who prefer declarative config, with no Java required; or Java profiles for advanced logic and full control.

Both produce standard MVT usable by MapLibre GL, Mapbox GL and other clients. The YAML path is powered by a module called `planetiler-custommap`, with examples and documentation in that directory of the repository.

A YAML profile starts with a schema name, an attribution string, a source and a list of layers:

schema_name: Roads
attribution: <a href="https://www.openstreetmap.org/copyright">&copy; OpenStreetMap contributors</a>
sources:
  osm:
    type: osm
    url: geofabrik:rhode-island
layers:
- id: roads
  features:
  - source: osm
    geometry: line
    min_zoom: 6

The `geofabrik:rhode-island` source shorthand is a nice touch, since it means a profile can name a regional extract without hardcoding a URL.

The repository tree shows the module structure behind this, and it explains a lot about the project's shape: `planetiler-core` holds the engine, `planetiler-custommap` the YAML path, `planetiler-examples` sample profiles, `planetiler-dist` the packaging that produces the jar, `planetiler-benchmarks` performance measurement, and `planetiler-openmaptiles` the OpenMapTiles profile itself as a submodule. There is also a `layerstats/` directory and a `planet-logs/` directory, which are what you would expect from a project that profiles whole-planet builds rather than toy inputs.

How the sorting model works, and where the docs go

The README gives the algorithm in two sentences, which is enough to understand the design: Planetiler maps input elements to vector tile features, flattens them into one big list, then sorts by tile ID to group them into tiles.

That single sentence explains the whole memory story. There is no spatial index that has to be kept in memory and no database doing range queries, because the sort happens once, on disk if necessary, and grouping by a sortable key is cheap. The cost is a temporary file as large as the flattened feature list, which is where the disk guidance of five to ten times the input size comes from.

There is an `ARCHITECTURE.md` in the root, linked from exactly that paragraph, plus a linked blog post for longer backstory. `PLANET.md` covers generating a whole planet rather than an extract, which is deliberately a separate document because the resource requirements differ by orders of magnitude.

For a planet build, the repository also includes a `grafana.json` and a `planet-logs/` directory, and release notes mention a `--parallel-tmp-io` flag added specifically to improve throughput when using ramdisk. That is a strong hint about how the intended production workflow looks: run the tile generation against a ramdisk-backed temporary directory so the sort never touches spinning disk.

Release cadence, the Overture question, and reading the metadata

Two recent releases show the shape of development. Version 0.10.1 on 2026-03-10 fixed a node location out-of-memory error and a hang, fixed an ArrayIndexOutOfBoundsException with `--mlt-fastpfor` enabled, made polygon merging more robust in response to an upstream issue on Protomaps basemaps, and included optimistic naive polygon snapping for a stated 20 percent runtime reduction, plus the new `--parallel-tmp-io` flag.

Version 0.10.2 on 2026-03-29 added support for generating tiles to zoom level 16, added STAC-based selective Overture download, and added an example overlay profile together with a ParksOverlay example with a MapLibre style.

A few observations. The version numbers are pre-1.0 and the tags are dated, while the repository's last push is 2026-09-28, so there is work on `main` that postdates the newest tag by roughly six months. If you need current behaviour, build from source rather than assuming the release is current.

On data sources: the repository topics include `overture`, and the v0.10.2 release adds selective Overture downloads via STAC, but the usage documentation in the README is entirely OpenStreetMap-centric, with Geofabrik extracts and an `--osm-path` flag and no Overture flag listed among the common arguments. Both facts hold, and the practical reading is that OSM is the documented path and Overture is newer and less documented.

For scale, the project has 2,193 stars, 193 forks and 113 open issues, and there are three separate full basemaps built on it: OpenMapTiles, Protomaps Basemaps and Shortbread, which ships as a YAML sample inside the repository itself. A project used as the foundation for three independent basemap schemas is past the point where you need to worry whether the approach holds up.

Editorial conclusion

Planetiler is the tool to reach for when you want an OpenMapTiles schema basemap without standing up a PostGIS instance, and the YAML profile module extends that to custom layers without writing Java. The memory guidance in the README is specific enough to plan around, roughly half the input PBF size in RAM and five to ten times it in disk, and the one command that produces a real tileset is short enough to try this week. Two cautions: the OpenMapTiles profile pulls about 1GB of ocean and Natural Earth data before it does anything, and releases move slowly relative to the commit history. Run the Monaco extract first, open the mbtiles in tileserver-gl-light, and only then plan the disk and memory for a full planet build.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. onthegomap/planetiler on GitHub
4. README
5. Releases