PMTiles

3.7.0 verified Fri May 01 auth: no python

Library and utilities to write and read PMTiles archives — cloud-optimized archives of map tiles. Version 3.7.0, actively maintained with frequent releases.

pip install pmtiles

Common errors

error ImportError: cannot import name 'Reader' from 'pmtiles' ↓

cause In v3, Reader is no longer in the top-level package.

fix

Replace from pmtiles import Reader with from pmtiles.reader import Reader.

error AttributeError: 'Reader' object has no attribute 'open' ↓

cause The `open` method was removed in v3; use the constructor directly.

fix

Call Reader('path.pmtiles') instead of Reader().open('path.pmtiles').

Warnings

breaking In v3, the main import changed from `pmtiles` to submodules. Code using `import pmtiles` and accessing `pmtiles.Reader` will break. ↓

fix Use `from pmtiles.reader import Reader` or `from pmtiles.writer import Writer`.

deprecated The `Reader` no longer accepts an `open` keyword argument for custom file opening. Use a file-like object or a path. ↓

fix Pass a file path or a file-like object directly.

gotcha Tile coordinates use the Slippy Map tilename convention (x, y, z) with origin at top-left. y increases southward. ↓

fix Ensure tile coordinates follow the TMS standard (y=0 at top).

Imports

Reader

wrong

from pmtiles import Reader

correct

from pmtiles.reader import Reader

Reader is in the reader module, not top-level.

Writer

wrong

from pmtiles import Writer

correct

from pmtiles.writer import Writer

Writer is in the writer module.

Quickstart

Open a PMTiles archive, inspect header, and fetch a tile.

from pmtiles.reader import Reader

# Read from a local file or URL
reader = Reader('example.pmtiles')
header = reader.header()
print(header.tile_type, header.min_zoom, header.max_zoom)

# Fetch a tile at zoom 10, x 512, y 512
tile = reader.get_tile(10, 512, 512)
if tile:
    print(f'Tile size: {len(tile)} bytes')