Self-Host OpenStreetMap Vector Tiles with PMTiles

What PMTiles Is and Why It Works

A classic tile server answers millions of small questions: give me tile z/x/y. PMTiles flips the model. All tiles are packed into one archive with an index, and the client asks for byte ranges of that one file. Object storage and CDNs are extremely good at serving byte ranges, so the entire serving stack becomes: one file, one bucket.

• No server to maintain: there is nothing to patch, restart or scale.
• Cheap by design: storage is pennies per gigabyte and range reads are fractions of a cent per million on R2.
• Portable: the same file works locally, on any S3-compatible storage, or behind a CDN.

Step 1: Get the Data

Protomaps builds the full OpenStreetMap planet into PMTiles every day at build.protomaps.com. The planet is around 120 GB, but you almost never need it. The pmtiles CLI extracts a region directly from the remote file:

# download the CLI from github.com/protomaps/go-pmtiles/releases

pmtiles extract https://build.protomaps.com/20260701.pmtiles turkiye.pmtiles \
  --bbox=25.5,35.6,45.0,42.4 --download-threads=8

The bbox above covers Türkiye; swap in any bounding box or pass a GeoJSON boundary with the region flag. Only the bytes belonging to your region are downloaded. A country-sized extract typically lands in the low gigabytes; if size matters, add a maxzoom flag (zoom 14 halves the archive again and still looks sharp for most use cases).

Sanity-check the result before uploading:

pmtiles show turkiye.pmtiles

Step 2: Host It on Cloudflare R2

Any S3-compatible storage works. We like Cloudflare R2 because egress is free, which is exactly the cost profile a public map needs. Create a bucket, upload the archive (rclone handles multi-gigabyte multipart uploads well) and attach a custom domain.

rclone copyto turkiye.pmtiles r2:my-maps/v1/tiles/turkiye.pmtiles

Browsers reading PMTiles need a CORS policy that allows range requests and exposes ETag:

[{
  "AllowedOrigins": ["*"],
  "AllowedMethods": ["GET", "HEAD"],
  "AllowedHeaders": ["range", "if-match"],
  "ExposeHeaders": ["etag"],
  "MaxAgeSeconds": 3000
}]

Step 3: Read It from MapLibre GL

There are two serving patterns, and they are not mutually exclusive:

Pattern A: browser-direct with the pmtiles protocol

The pmtiles JavaScript package teaches MapLibre a pmtiles:// URL scheme. No infrastructure at all beyond the bucket:

import maplibregl from "maplibre-gl";
import { Protocol } from "pmtiles";

const protocol = new Protocol();
maplibregl.addProtocol("pmtiles", protocol.tile);

const map = new maplibregl.Map({
  container: "map",
  style: {
    version: 8,
    sources: {
      protomaps: {
        type: "vector",
        url: "pmtiles://https://tiles.example.com/v1/tiles/turkiye.pmtiles",
        attribution: "Protomaps © OpenStreetMap"
      }
    },
    layers: [ /* your layers */ ]
  }
});

Pattern B: a tiny worker that speaks z/x/y

The PMTiles repository ships a ready-made Cloudflare Worker that reads the archive from R2 and exposes classic tile URLs plus TileJSON. The win: consumers need zero extra code, any stock MapLibre (or other tile client) can use the URL, and hot tiles get edge-cached. This is the pattern we use for our own public styles.

{
  "type": "vector",
  "url": "https://tiles.hititmedya.com/planet.json"
}

What It Costs

Compare that with per-request pricing of commercial map APIs and the difference at scale is one to two orders of magnitude. The real recurring cost is not money, it is the monthly data refresh, which is one extract command and one upload.

Attribution Is Not Optional

OpenStreetMap data is licensed under ODbL. Wherever the map is shown, you must display attribution to OpenStreetMap. In MapLibre, set the attribution field on the source and leave the attribution control on. Crediting Protomaps for the builds is good practice too.

Frequently Asked Questions

Sources and References