geodataframe-to-pmtiles

Write PMTiles vector archives from one or more GeoPandas GeoDataFrames using GDAL directly — no subprocesses, no temporary files.

Install

After version 0.1.0 is published to PyPI, install it with:

pip install geodataframe-to-pmtiles

Until then, install a source checkout:

git clone https://github.com/palewire/geodataframe-to-pmtiles.git
cd geodataframe-to-pmtiles
uv sync

Note: The library itself is pure Python, but gpm.write() needs a native GDAL runtime with the PMTiles driver available. The package imports without GDAL; calling gpm.write() without it raises a clear RuntimeError. In CI we install GDAL from conda-forge. Locally, install GDAL separately via conda-forge, Homebrew, or your operating system package manager before writing PMTiles archives.

Diagnose GDAL

After installing GDAL, check that its Python bindings, native library, PMTiles driver, and a real in-memory write all work:

python -m geodataframe_to_pmtiles check
python -m geodataframe_to_pmtiles check --json

--json prints a small, stable report that is safe to include in a bug report. The check runs only when requested; it is not an install hook. Conda-forge is the most reliable setup on every platform. On macOS, install GDAL with Homebrew and use Python bindings built for that installation. On Linux, install matching GDAL runtime and Python packages from the same system package source.

Usage

import geopandas as gpd
from pathlib import Path
import geodataframe_to_pmtiles as gpm

# Any explicit CRS is accepted — reprojection to EPSG:4326 is automatic.
points = gpd.read_file("points.geojson")
polygons = gpd.read_file("polys.geojson")

gpm.write(
    {"points": points, "polygons": polygons},
    Path("output.pmtiles"),
    min_zoom=0,
    max_zoom=8,
    name="my map",
    description="Points and polygons",
    on_overflow="error",  # default: reject reported tile-level data loss
    attribution="© OpenStreetMap contributors",  # optional; stored in TileJSON metadata
)

GeoDataFrames passed to gpm.write() must already carry a CRS. If your source format does not store CRS metadata, set one before writing:

points = points.set_crs("EPSG:4326")
polygons = polygons.set_crs("EPSG:4326")

Write to a BytesIO stream instead of a file:

import io

buf = io.BytesIO()
gpm.write({"points": points}, buf)

Write a single GeoDataFrame with an explicit layer name:

import geodataframe_to_pmtiles as gpm

gpm.write(points, Path("output.pmtiles"), layer="points")

Test coverage

The test suite includes semantic conformance checks that write tracked climate and Tippecanoe fixtures through GDAL, then decode the resulting PMTiles archives with the official pmtiles reader and mapbox-vector-tile. The tests assert header metadata, source-layer names, property schemas, hole preservation, and feature order while ignoring raw bytes and protobuf ordering.

Documentation

The single-page documentation source is docs/index.md and is built in CI. Deployment remains disabled pending explicit approval and the first deployment. Once published, the public documentation URL will be https://palewi.re/docs/geodataframe-to-pmtiles/.

gpm.write — two call forms

Mapping form — multiple named layers:

gpm.write({"name": gdf, ...}, output, *, min_zoom, max_zoom, ...)

Single-frame form — one layer with an explicit name:

gpm.write(gdf, output, *, layer="name", min_zoom, max_zoom, ...)

Property normalisation

Boolean columns may contain nulls, including pandas BooleanDtype values even if every value is null. They must not mix booleans with numeric 0 or 1: those are integers and remain numeric. Mixed scalar boolean/non-boolean columns raise UnsupportedPropertyTypeError instead of silently changing values.

Exceptions

Overflow policy

GDAL's MVT encoder can drop features after MAX_FEATURES is reached and reduce geometry precision after MAX_SIZE is exceeded. The writer uses practical limits (300,000 features and 10 MB per tile) and captures the encoder's diagnostics during finalization. The default on_overflow="error" raises TileOverflowError and leaves the Path or stream untouched when either action occurs. Its violations describe the limit, configured value, observed value, and tile coordinate when GDAL reports one.

The 200,001-feature z0 spike remains supported and is independently decoded in the test suite. This is not a capacity promise: a clustered layer or dense geometry can still exceed a tile limit, but it cannot be published through the default API after GDAL reports that action.

on_overflow="unsafe" is an explicit opt-out. It emits a warning and may publish an archive with missing features or lower-precision geometry.

Climate-monitor guidance

Use the default policy for climate cell layers and treat TileOverflowError as a signal to split the layer or lower its density at the affected zoom. Do not use on_overflow="unsafe" for maps where holes or coordinate changes would alter reported conditions.

Known limitations

• Feature count inflation when reading back: MVT stores features in every intersecting tile; read-back counts exceed input counts. This is not data loss.
• Simplification disabled by default: pass simplification=<float> to enable.

Development

make install
make check   # lint, format, type checks
make verify  # full suite: checks, tests, build, docs

See AGENTS.md and CONTRIBUTING.md.