pmtiles CLI ​

Installation ​

pmtiles is a single binary with no external dependencies.

The source code is on GitHub at protomaps/go-pmtiles.

To download, see Releases on GitHub for your OS and architecture.

An official Docker Hub image is available at protomaps/go-pmtiles.

CLI Overview ​

Local archives ​

The CLI works with local tilesets on disk, for example:

pmtiles show test.pmtiles

pmtiles show test.pmtiles

Remote archives ​

However, pmtiles can also work with remote HTTP archives and tilesets on cloud storage, even in private buckets.

pmtiles show https://r2-public.protomaps.com/protomaps-sample-datasets/cb_2018_us_zcta510_500k.pmtiles

pmtiles show https://r2-public.protomaps.com/protomaps-sample-datasets/cb_2018_us_zcta510_500k.pmtiles

pmtiles uses the go-cloud library for connecting and authenticating to cloud storage.

Commands for S3, Azure Blob and Google Cloud Storage:

pmtiles show test.pmtiles --bucket=s3://BUCKET_NAME
pmtiles show test.pmtiles --bucket=azblob://CONTAINER_NAME?storage_account=ACCOUNT
pmtiles show test.pmtiles --bucket=gs://BUCKET_NAME

pmtiles show test.pmtiles --bucket=s3://BUCKET_NAME
pmtiles show test.pmtiles --bucket=azblob://CONTAINER_NAME?storage_account=ACCOUNT
pmtiles show test.pmtiles --bucket=gs://BUCKET_NAME

For S3-compatible blob storage (Minio, Cloudflare R2, etc) outside of AWS:

pmtiles show test.pmtiles --bucket=s3://BUCKET_NAME?endpoint=https://example.com&region=auto

pmtiles show test.pmtiles --bucket=s3://BUCKET_NAME?endpoint=https://example.com&region=auto

Private buckets ​

pmtiles uses go-cloud's default authentication methods for each cloud provider.

For example, the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables are used to sign requests to private S3-compatible buckets:

export AWS_ACCESS_KEY_ID=MY_KEY
export AWS_SECRET_ACCESS_KEY=MY_SECRET
pmtiles show NAME.pmtiles --bucket=s3://R2_BUCKET_NAME\?endpoint=https://R2_ACCOUNT_ID.r2.cloudflarestorage.com\&region=auto

export AWS_ACCESS_KEY_ID=MY_KEY
export AWS_SECRET_ACCESS_KEY=MY_SECRET
pmtiles show NAME.pmtiles --bucket=s3://R2_BUCKET_NAME\?endpoint=https://R2_ACCOUNT_ID.r2.cloudflarestorage.com\&region=auto

Commands ​

show ​

pmtiles show INPUT.pmtiles
pmtiles show INPUT.pmtiles --bucket=s3://BUCKET_NAME

pmtiles show INPUT.pmtiles
pmtiles show INPUT.pmtiles --bucket=s3://BUCKET_NAME

Print an archive's header data and metadata.

tile ​

pmtiles tile INPUT.pmtiles 0 0 0

pmtiles tile INPUT.pmtiles 0 0 0

Output a single tile's contents to stdout.

verify ​

pmtiles verify INPUT.pmtiles

pmtiles verify INPUT.pmtiles

Check that an archive is ordered correctly and has correct header information.

extract ​

pmtiles extract INPUT.pmtiles OUTPUT.pmtiles --bbox=MIN_LON,MIN_LAT,MAX_LON,MAX_LAT
pmtiles extract INPUT.pmtiles OUTPUT.pmtiles --region=REGION.geojson
pmtiles extract https://example.com/INPUT.pmtiles OUTPUT.pmtiles --maxzoom=MAXZOOM
pmtiles extract INPUT.pmtiles OUTPUT.pmtiles --maxzoom=MAXZOOM --bucket=s3://BUCKET_NAME

pmtiles extract INPUT.pmtiles OUTPUT.pmtiles --bbox=MIN_LON,MIN_LAT,MAX_LON,MAX_LAT
pmtiles extract INPUT.pmtiles OUTPUT.pmtiles --region=REGION.geojson
pmtiles extract https://example.com/INPUT.pmtiles OUTPUT.pmtiles --maxzoom=MAXZOOM
pmtiles extract INPUT.pmtiles OUTPUT.pmtiles --maxzoom=MAXZOOM --bucket=s3://BUCKET_NAME

Create a smaller archive from a larger archive. The source archive may be local or remote. The source archive must be clustered.

Options:

• --maxzoom: Extract only a subset of zoom levels. Extracting a full sub-pyramid from 0 to maxzoom is always an efficient operation that makes minimal I/O or network requests to the source archive.
• --minzoom: Extract only a partial sub-pyramid. This may require many more requests than leaving the default --minzoom=0. Because this removes overview zoom levels, it should only be used in specific situations.
• --region: a GeoJSON Polygon, Multipolygon, Feature, or FeatureCollection.
• --download-threads Number of parallel requests to speed up downloads.
• --overfetch extra data to download to batch small requests: 0.05 is 5%.

serve ​

The simplest way to consume PMTiles on the web is directly in the browser with pmtiles.js along with a renderer-specific client. However, decoding PMTiles on the server and exposing a ZXY API works with more clients and can result in lower latency. A ZXY API is directly supported by web and native renderers such as MapLibre, without needing the PMTiles client library. Using pmtiles serve also allows serving a public API from a private storage bucket.

Serve a directory or bucket of tilesets (like TILESET.pmtiles) from local or cloud storage as a ZXY endpoint:

pmtiles serve .
# serves this directory at http://localhost:8080/TILESET/{z}/{x}/{y}.mvt 
# the .pmtiles extension is added automatically
# TileJSON at http://localhost:8080/TILESET.json
pmtiles serve . --bucket=https://example.com
pmtiles serve / --bucket=s3://BUCKET_NAME
pmtiles serve PREFIX --bucket=s3://BUCKET_NAME

pmtiles serve .
# serves this directory at http://localhost:8080/TILESET/{z}/{x}/{y}.mvt 
# the .pmtiles extension is added automatically
# TileJSON at http://localhost:8080/TILESET.json
pmtiles serve . --bucket=https://example.com
pmtiles serve / --bucket=s3://BUCKET_NAME
pmtiles serve PREFIX --bucket=s3://BUCKET_NAME

For ZXY URLs, the extension must match the type of the tiles in the archive, for example mvt, png, jpg, webp, avif.

Flags:

• --cors=ORIGIN set the value of the Access-Control-Allow-Origin. * is a valid value but must be escaped in your shell. Appropriate for development use.
• --cache-size=SIZE_MB set the global size of the header and directory LRU cache, shared across all archives. Default is 64 MB.
• --port=PORT specify the HTTP port. Defaults to 8080.
• --public-url: Required for serving TileJSON. Specify the full URL as it should appear to the browser client like http://localhost:8080 or https://example.com.

For production usage, it's recommended to run behind a CDN or reverse proxy like Caddy to handle SSL and CORS. See the guide on Accelerating PMTiles.

convert ​

Convert an MBTiles archive to PMTiles.

pmtiles convert INPUT.mbtiles OUTPUT.pmtiles

pmtiles convert INPUT.mbtiles OUTPUT.pmtiles

For the Docker image:

docker run -v $(pwd):/data --rm protomaps/go-pmtiles convert /data/INPUT.mbtiles /data/OUTPUT.pmtiles

docker run -v $(pwd):/data --rm protomaps/go-pmtiles convert /data/INPUT.mbtiles /data/OUTPUT.pmtiles

Options:

• --no-deduplication: Do not attempt to de-duplicate tile contents. Use this to speed up convert if you know the input has only unique tiles.
• --tmpdir: specify the location of the temporary directory.

upload ​

Upload an archive to cloud storage.

# requires environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY credentials
pmtiles upload INPUT.pmtiles REMOTE.pmtiles --bucket=s3://BUCKET_NAME

# requires environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY credentials
pmtiles upload INPUT.pmtiles REMOTE.pmtiles --bucket=s3://BUCKET_NAME

You will need write permissions to the bucket, for example this AWS IAM policy:

  {
      "Version": "2012-10-17",
      "Statement": [
          {
              "Effect": "Allow",
              "Action": "s3:*",
              "Resource": "arn:aws:s3:::my-bucket-name/*"
          }
      ]
  }

  {
      "Version": "2012-10-17",
      "Statement": [
          {
              "Effect": "Allow",
              "Action": "s3:*",
              "Resource": "arn:aws:s3:::my-bucket-name/*"
          }
      ]
  }

version ​

pmtiles version

pmtiles version

Print the version of the command line tool.