pmtiles CLI reference

pmtiles show

$ pmtiles show FILE.pmtiles

displays the header information and metadata of a local archive.

$ pmtiles show https://maps.cusy.io/map.pmtiles

displays the header information and metadata of a remote HTTPS archive.

$ pmtiles show FILE.pmtiles --bucket=s3://BUCKET

displays the header information and metadata of an archive that is located on an S3-compatible bucket.

$ pmtiles show FILE.pmtiles --header-json

outputs a JSON representation of the header.

$ pmtiles show FILE.pmtiles --metadata

outputs the JSON metadata.

Note

URLs with characters such as ? and & should be escaped with a backslash \.

pmtiles tile

$ pmtiles tile FILE.pmtiles 0 0 0

outputs the content of a single tile.

pmtiles verify

$ pmtiles verify FILE.pmtiles

checks whether an archive is correctly organised and contains correct header information.

pmtiles extract

$ pmtiles extract

creates a smaller archive from a larger one, whereby the source archive must be clustered:

$ pmtiles extract IN.pmtiles OUT.pmtiles --bbox=MIN_LON,MIN_LAT,MAX_LON,MAX_LAT

You can determine the bounding box with MIN_LON, MIN_LAT, AX_LON and MAX_LAT with bboxfinder.com, for example.

$ pmtiles extract IN.pmtiles OUT.pmtiles --region=REGION.geojson

A GeoJSON Polygon, Multipolygon, Feature or a FeatureCollection object can be specified with --region.

$ pmtiles extract https://EXAMPLE.COM/IN.pmtiles OUT.pmtiles --maxzoom=MAXZOOM --download-threads=4

--maxzoom extracts only a subset of the zoom levels.

--download-threads specifies the number of parallel requests to speed up the downloads.

$ pmtiles extract IN.pmtiles OUT.pmtiles --maxzoom=MAXZOOM --bucket=s3://BUCKET

Further options are:

--minzoom

extracts only part of the pyramid, but this may require many more requests than the default --minzoom=0. As this removes the overview zoom levels, it should only be used in certain situations.

--overfetch

downloads additional data to bundle small requests: 0.05 corresponds to 5 %.

pmtiles serve

$ pmtiles serve

is an easy way to serve PMTiles together with pmtiles.js on the web:

$ pmtiles serve PATH

serves a TILESET.pmtiles file from the PATH directory at the http://localhost:8080/TILESET/Z/X/Y.mvt|png|jpg|webp|avif, where the suffix must match the tile type in the archive.

$ pmtiles serve . --public-url=localhost

allows the output of TileJSON under the URL http://localhost:8080/TILESET.json.

pmtiles convert

$ pmtiles convert

converts an MBTiles archive into PMTiles:

$ pmtiles convert IN.mbtiles OUT.pmtiles

--no-deduplication

Tile contents should usually be de-duplicated. Use this only if you know that the input contains only unique tiles and you want to speed up the conversion.

--tmpdir

allows you to specify the temporary directory.

pmtiles cluster

pmtiles cluster IN.pmtiles

clusters an existing archive, optimising the size and layout. Archives created with tippecanoe, planetiler and pmtiles CLI are already clustered.

--no-deduplication

Tile contents should usually be de-duplicated. Use this only if you know that the input contains only unique tiles and you want to speed up the conversion.

pmtiles upload

pmtiles upload IN.pmtiles REMOTE.pmtiles --bucket=s3://BUCKET

uploads an archive to the cloud storage.

pmtiles edit

pmtiles edit NAME.pmtiles --header-json=HEADER.json --metadata=METADATA.json

changes parts of the archive header, or replaces the JSON metadata of the archive. If you only edit the header, the file will be changed in place; however, writing the JSON metadata requires writing a new copy of the archive, which then replaces NAME.pmtiles.

Hint

You can write the existing header information and metadata to the HEADER.json and METADATA.json files with:

pmtiles show NAME.pmtiles --header-json > HEADER.json

or

pmtiles show NAME.pmtiles --metadata > METADATA.json

Hint

The fields tile_type, tile_compresssion, minzoom, maxzoom, bounds and centre of the header can be edited; however, other fields cannot be edited.

pmtiles version

pmtiles version

outputs the version from pmtiles.