Source: Protomaps, PMTiles format and tools (protomaps/PMTiles, spec v3) and Protomaps Basemaps (protomaps/basemaps). Code BSD-3, map design CC0, OpenStreetMap-derived tiles ODbL. Highlighted on LinkedIn by André Lindenberg, 2026-11-16.
The idea
Web maps usually mean either paying a provider per map load or running a tile server that answers z/x/y tile requests from a database. PMTiles replaces the server with a file. A whole tileset, up to a planet-scale OpenStreetMap basemap, is packed into one archive placed on commodity object storage (S3, R2 or any host that supports HTTP Range). The browser client (MapLibre GL JS, Leaflet or OpenLayers plug-ins) computes which bytes hold the tile it needs and fetches just those bytes with a range request. For a basemap, there is no backend to operate.
How the format makes that work
Fixed 127-byte header at the start of the file with offsets and lengths of every other section.
Root directory within the first 16 KiB, so a client can fetch header and root directory in a single initial request.
JSON metadata (layers, attribution, bounds).
Optional leaf directories for large tilesets, so directory lookups stay at most a couple of extra range reads.
Tile data, with identical tiles (ocean, empty land) deduplicated.
Tiles are addressed along a Hilbert curve so spatially nearby tiles are near each other in the file, which helps both compression of directories and caching. A planet basemap can be built from OpenStreetMap and Natural Earth with a Planetiler profile in a few hours on a modest machine; pmtiles convert and pmtiles upload handle conversion from MBTiles and upload.
The general pattern
PMTiles is one instance of cloud-optimized single-file formats: Cloud Optimized GeoTIFF, Parquet with footers and row-group statistics, and similar designs. The recipe is the same: a small index at a known offset, data laid out for locality, and clients that turn logical lookups into byte-range reads. It trades a running service for a smarter client and a CDN.
Tradeoffs
Read-only. Updates mean building and replacing the whole file. Fine for basemaps refreshed weekly or monthly; wrong for live editing or per-user data.
Request count and latency. A cold map view may need a header read, a directory read and several tile reads; edge caching and HTTP/2 matter. A tile server with an in-memory cache can be faster on first paint.
No server-side logic. Styling, filtering, authorization and per-request transformation move to the client or a thin edge function.
Storage and egress pricing replace compute pricing; on providers with free egress the economics are very good, elsewhere range-request volume can add up.
Cache semantics. Replacing a file in place while clients hold old directory offsets can serve mismatched bytes; versioned filenames or ETag checks are needed.
Failure modes
Hosts or CDNs that ignore Range headers or strip them, returning the whole file.
Missing CORS configuration on the bucket, so browser clients fail silently.
Atomic replacement not guaranteed during updates; clients see a half-old, half-new archive.
Attribution obligations for ODbL data forgotten when the map is self-hosted.
Review checklist
Is the dataset read-mostly with infrequent rebuilds?
Does the storage or CDN support Range requests, CORS and long cache lifetimes?
Are archives versioned by name, with the client pointed at a new URL on update?
Is first-paint latency acceptable with cold caches from the farthest region?
Are licence and attribution requirements for the data handled in the UI?
Related
R046 Hardwood: a remote file reader is really a scheduler (the same range-request pattern for Parquet).
R072 llama.cpp 1.0 (single-file local artefacts and local-first serving).