PMTiles Viewer

What this tool does

A PMTiles file is a single flat binary archive of map tiles, built so that individual tiles can be pulled out using plain HTTP byte-range requests instead of a database query or a running tile server. That efficiency comes at a cost for a human trying to look inside one: there is no built-in way to see what a .pmtiles file actually contains without either wiring up a map library yourself or running it through a command-line tool.

This viewer removes that step. Drop in a file and it reads the archive's 127-byte header and JSON metadata to report the tile format, zoom range, geographic bounds, and any name, description, or attribution the file carries, then renders every visible tile directly on a Leaflet map. Everything happens locally: the file is read straight off your disk using the browser's File API, and nothing is ever sent to a server.

How the viewer reads a PMTiles file

The viewer uses the official "pmtiles" JavaScript library, the same reader implementation used by MapLibre GL, paired with a File-based source that lets it pull byte ranges directly out of an uploaded file rather than over HTTP. That first read fetches only the header and the compressed tile directory, which is enough to report the archive's zoom range, bounds, and format immediately, before any tile has been decoded.

As you pan and zoom the map, each visible tile is requested by its z/x/y coordinate. The reader looks that coordinate up in the archive's directory, which is organized by a Hilbert-curve tile ID, does a binary search to find the tile's byte offset and length, fetches exactly those bytes, and hands back the raw tile image. A small custom Leaflet layer wraps that lookup so tiles simply appear on the map as you'd expect from any other tile source, including reusing the nearest available tile when you zoom in past the archive's recorded maximum zoom.

PMTiles: history and technical facts

PMTiles comes from Protomaps, an open source mapping project built on the idea that a map does not need a server behind it, only a well organized file and something able to serve byte ranges. Protomaps publishes the PMTiles specification itself as public domain, while the reference reader and writer implementations, in Go, JavaScript, Python, and several other languages, are released under the BSD 3-Clause license. The format has gone through more than one iteration; the current and only actively used version, v3, replaced earlier layouts with the Hilbert-curve directory this site's own MBTiles to PMTiles converter also implements.

The problem PMTiles solves is mostly one of cost and complexity. A full worldwide tile pyramid can hold hundreds of millions of individual tiles. Protomaps' own documentation gives an example of 300 million tiles that, stored as separate objects, could cost around $1,500 in cloud storage request fees and take days to upload. A single PMTiles archive packs that whole pyramid into one file, deduplicates identical tiles internally (Protomaps reports size reductions of 70% or more for global vector basemaps), and lets a plain static file host such as S3, Cloudflare R2, or GitHub Pages serve individual tiles through ordinary HTTP range requests, with no tile server, database, or serverless function required, though it also runs well from AWS Lambda or Cloudflare Workers if you do want one in front of it.

A few technical facts worth knowing: official reader libraries exist for JavaScript, Python, Dart, Kotlin/JVM, Go, C++, and Rust, and the format is supported directly by MapLibre GL JS, Leaflet, and OpenLayers. PMTiles is read only by design; there is no way to update a handful of tiles inside an existing archive without rewriting the whole file, a deliberate trade-off for the format's simplicity and its single-file, byte-range-friendly layout. The header itself is a fixed 127 bytes, small enough that a reader fetches it in a single request and immediately knows an archive's zoom range, bounds, tile format, and tile count, before reading a single tile.

Step-by-step guide

Step 1

Click "Upload PMTiles" and choose a .pmtiles file, drag and drop one onto the panel, or click "Try Sample PMTiles" to load a small example generated on the spot.

Step 2

The archive's tiles are read directly from the file and drawn on the map. The file info panel shows the tile count, format, zoom range, bounds, and any metadata straight from the file's own header.

Real-world use cases

Where opening a PMTiles file directly, without writing any code, actually helps.

1. Checking a PMTiles file before publishing it. After building or converting a PMTiles archive, opening it here confirms the zoom range, bounds, and tile format are correct before uploading it to a static file host.
2. Inspecting a downloaded open dataset. Projects that distribute PMTiles extracts, such as regional cuts of a larger basemap, can be opened directly to see what they contain before writing any code against them.
3. Verifying an MBTiles-to-PMTiles conversion. After converting a file with a tool like this site's MBTiles to PMTiles converter, loading the result back into this viewer confirms every tile ended up in the right place.
4. Reviewing a basemap before deploying a map app. Teams building an offline-capable or self-hosted map can preview the exact PMTiles archive their app will load, catching a wrong zoom range or an empty area before it ships.
5. Auditing an archived tileset. Since PMTiles carries its own metadata (name, description, attribution, bounds), a years-old archived file can still be identified and checked without any external documentation.

Frequently asked questions