What Is PMTiles?

PMTiles is a single-file archive format for tiled map data. Instead of storing millions of map tiles as separate files or requiring a custom tile server, a PMTiles archive packages the tile pyramid and directory information into one file that clients can access using HTTP byte-range requests.

The current PMTiles specification is version 3.

PMTiles can contain vector tiles or raster image tiles. It is a delivery/archive format for tiles, not a replacement for the full-fidelity source dataset from which those tiles were generated.

Why tile archives exist

A global or national tile pyramid can contain an enormous number of logical tile addresses across zoom levels.

One approach is to store each tile as an individual object, such as:

/{z}/{x}/{y}.mvt

That works, but millions of tiny files can be cumbersome to create, upload, list, cache, and manage. A tile archive instead stores those logical tiles inside a smaller number of physical files—PMTiles uses one.

How random access works

A PMTiles client does not download the whole archive before showing a map.

The file contains a header and directory structures describing where tile contents live, allowing a client to read the relevant directory information and then request the byte ranges containing the needed tiles.

That access model allows the archive to sit on static object storage while the map behaves like a conventional tiled service.

The v3 specification constrains the root-directory area so clients can discover tile locations efficiently and uses hierarchical directories when necessary for large archives.

PMTiles can store different tile types

Version 3 defines tile-type identifiers including MVT vector tiles and several raster image types such as PNG, JPEG, WebP, and AVIF, as well as MapLibre Tile content.

This is important because PMTiles does not define the feature encoding inside an MVT tile; it defines the archive structure that locates and retrieves tiles.

A vector-tile archive therefore combines two concepts:

PMTiles for single-file indexing and byte access;
a vector-tile specification for the contents of each tile.

PMTiles is not the same as GeoParquet

GeoParquet is oriented towards analytical vector tables. PMTiles is oriented towards map-tile delivery.

A GeoParquet file preserves feature rows and columns for analytical reading, whereas a PMTiles archive contains already tiled representations organised by zoom and location.

A production system may use GeoParquet as a source and generate PMTiles for publication. The two formats solve different stages of the workflow.

PMTiles is not an editable GIS project container

It is also different from GeoPackage.

GeoPackage is a SQLite database standard that can store editable vector tables and tile matrix sets, while PMTiles is a purpose-built immutable-style archive for efficient tiled access from static storage.

If users need to edit features, run arbitrary spatial queries, or preserve a rich relational schema, the source should live elsewhere.

When PMTiles is attractive

PMTiles is useful when:

a map can be represented as a tiled pyramid;
you want to host tiles on simple object/static storage;
one archive is easier to distribute than millions of small files;
clients support PMTiles range access;
the tileset is generated ahead of time or updated as versioned archives.

It is less appropriate when the application requires highly dynamic per-request tile generation from rapidly changing source data.

Treat the archive as a publication representation

Tiling can clip geometries at tile boundaries, simplify detail by zoom, omit attributes, aggregate points, or encode only what the map needs.

Those are often desirable publication optimisations, but they also mean the archive should not automatically replace the authoritative analytical source.

Keep the source dataset and generation process if reproducibility, re-styling, re-analysis, or export matters.

References

PMTiles v3 Specification. Defines PMTiles as a single-file archive format and documents header, directories, tile types, and metadata.
PMTiles project. Reference implementations and current-version documentation.