Skip to main content

Using PMTiles

PMTiles is a single-file archive format for pyramids of tiled data. A PMTiles archive can be hosted on a storage platform like S3, and enables low-cost, zero-maintenance map applications. See Storage Providers for how to host PMTiles on your own service.

Why use PMTiles?#

Protomaps provides vector basemap cartographic tiles derived from OpenStreetMap in the PMTiles format. Try this out at Getting Started. With a vector basemap PMTiles archive for an area, you can create a map application that requires no API key or server maintenence, under your own control and at minimal cost.

PMTiles is a general, simple format for any tiled data that is addressed by Z, X and Y. This can be cartographic basemap data, machine-readable tiles for routing or labeled ML features, overlay layers, JPEGs and more. While PMTiles is designed for slippy maps on the web, it can be used for any kind of zoomable data.

pmtiles for JavaScript#

Use with Leaflet#

A simple adapter is included for displaying PMTiles of raster images in Leaflet.

For displaying Vector Tiles in Leaflet, use protomaps.js.


Decoding PMTiles on the browser does not support general-purpose compression using the Accept-Encoding and Content-Encoding headers, because it depends on HTTP Byte Serving via Range headers. Within a PMTiles archive of MVT (Protobuf)-encoded vector features, each tile must exist in the archive in decompressed form without gzip compression applied.

This limitation is acceptable for many use cases. For demanding applications, you can decode PMTiles to Z/X/Y on a server, or use our CDN-accelerated, hosted service.

pmtiles for Python#

pmtiles is a python package that can be installed via pip, and focuses on interacting with PMTiles files on disk instead of via HTTP. It's available on GitHub and via the Python Package Index.

pip install pmtilespmtiles-show INPUT.pmtilespmtiles-serve INPUT.pmtiles # will run a server for decoding to Z/X/Y paths


MBTiles is another single-file archive format for tiles, based on SQLite. Many GIS and visualization tools already support MBTiles. In many cases, MBTiles can be converted directly to PMTiles and vice-versa with no loss of information.

pmtiles-convert INPUT.mbtiles OUTPUT.pmtilespmtiles-convert INPUT.pmtiles OUTPUT.mbtiles

Z/X/Y directory trees#

Expanding your PMTiles to a directory tree is useful if you want to host your tiles at traditional Z/X/Y paths, but can become unwieldy with more than several thousand files, or needing to sync many files to a storage service.

pmtiles-convert INPUT.pmtiles OUTPUT_FOLDER

Library usage#