Building OSM Tiles with Tippecanoe

Tippecanoe will produce a usable tile set from OSM-derived GeoJSON with almost no configuration, and that is precisely the problem: the defaults make sensible choices on your behalf, and the first time a feature you cared about disappears at zoom 9 you will have no idea which choice did it.

What Tippecanoe does between GeoJSON input and an MBTiles archive GeoJSON features enter and are assigned to layers, either from a single input or one layer per input file. For each zoom level the features are filtered by their declared zoom range, simplified, and packed into tiles. When a tile exceeds the size budget, a dropping strategy removes features until it fits. The surviving features are encoded and written into an MBTiles archive alongside metadata describing the layers and zoom range. Four stages, and one of them silently removes data GeoJSON one file per layer assign zooms per feature range simplify per zoom tolerance drop to fit budget enforcement MBTiles tiles plus metadata The third stage is the one that makes features vanish, and by default it chooses which ones without consulting you.
Every complaint about Tippecanoe hiding data traces back to leaving the dropping stage on its defaults.

The Problem This Topic Solves

You have OSM features exported to GeoJSON and you need a tile set covering a range of zooms, with the right things visible at each. Tippecanoe is the shortest path from one to the other, and it is genuinely excellent at the hard part — making each tile fit a size budget while keeping the map legible.

The failure scenario is a map where things disappear unpredictably. A reviewer reports that a particular park is missing at zoom 11 but present at 12 and 10. Nothing in the pipeline logs an error. What happened is that the zoom-11 tile covering that area exceeded the size budget and the dropping stage removed features until it fit, choosing by its own heuristic — which is spatially uniform rather than importance-aware. In a dense tile, that means whichever features were unlucky.

Prerequisites

Have OSM features exported to GeoJSON, which is the job of Exporting OSM to GeoParquet & PostGIS or a direct osmium export. Understand the tile model from OSM Vector Tiles & Rendering Pipelines, and the geometry constraints from The Mapbox Vector Tile Spec & Tile Geometry.

The Model: Features Carry Their Own Zoom Range

The single most important idea is that every feature has a minimum and maximum zoom, and you can set it per feature rather than per layer. Tippecanoe reads this from reserved properties in the GeoJSON — tippecanoe:minzoom and tippecanoe:maxzoom — which means the decision about what appears when belongs in your export step, where you have the OSM tags, rather than in a command-line flag applied uniformly.

That is the mechanism that turns “features disappear unpredictably” into “features disappear exactly as I specified”. Compute a rank during layer assignment — road classification, water body area, settlement population, building footprint size — map that rank to a minimum zoom, and write it onto the feature. The dropping stage then has far less to do, because the tile is already the right size.

Four ways Tippecanoe can reduce a tile, and what each one costs A grid of four reduction mechanisms against what they remove and when each is appropriate. Explicit per-feature zoom ranges remove features you chose, at the zoom you chose, and are the preferred mechanism. Simplification removes vertices rather than features and is nearly always appropriate. Coalescing merges adjacent features with identical attributes, which is ideal for tiled polygon coverage. Automatic dropping to fit the size budget removes whichever features it must and should be a last resort rather than the primary control. Four reductions, in the order you should reach for them Removes Use it Per-feature zoom range features you chose always, first Simplification vertices, not features always Coalescing duplicate boundaries polygon coverage Automatic dropping whatever it must as a safety net The bottom row is the default behaviour, which is why an unconfigured run produces a map that reduces itself in ways nobody chose.
Each row above the last is a decision you make; the last row is a decision made for you when the others were not enough.

Preparing the GeoJSON Tippecanoe Wants

The generator’s input requirements are modest but specific, and the difference between input it handles gracefully and input it struggles with is worth getting right before a long build.

Line-delimited, not a feature collection. A single JSON document containing a million features has to be parsed as one object; the line-delimited form streams, can be split across files, and can be inspected with ordinary text tools. Every export path on this site can emit it, and there is no reason to prefer the alternative.

One file per layer. Naming layers explicitly on each input is what gives the archive a metadata record a style can be written against. Mixing several layers into one file and relying on an attribute to distinguish them works, but it means the layer separation happens at style time rather than at build time, which loses the per-layer zoom ranges entirely.

Consistent property types. A property that is an integer on some features and a string on others encodes unpredictably, because the per-layer value table has to accommodate both. This most often happens with numeric OSM tag values that are clean on most features and carry a unit or a range on a few — exactly the case the normalisation work in Normalizing OSM Speed Limits and Units exists to resolve. Coerce every property to one type during export.

Nothing you will not render. Features filtered out after the generator has read them have still been parsed, stored and sorted. A tag filter over the extract before export is the cheapest reduction available and routinely removes most of the input.

Geometry already valid. The generator does not repair geometry, and an invalid polygon produces unpredictable output rather than an error. Running the detection from Detecting Self-Intersecting OSM Polygons with Shapely over the export and quarantining what it flags costs one pass and removes a whole class of mysterious rendering artefacts.

Simplification, Coalescing and the Size Budget

Simplification reduces vertex counts per zoom. Tippecanoe’s default tolerance is reasonable, and the important thing is to remember it operates in tile grid units — simplifying further in your export step is usually wasted work, and simplifying less than the grid can represent is impossible to see.

Coalescing merges adjacent features that share identical attributes. For a polygon coverage — land use, administrative areas, building blocks — this is transformative at low zoom, because a thousand adjacent parcels with the same class become one polygon with one boundary instead of a thousand shared edges drawn twice each.

The size budget is the backstop. Tippecanoe targets a maximum tile size and will drop features to reach it. Leaving it at the default is fine; leaving dropping as your only reduction mechanism is not, because its choice of victim is not importance-aware. Configure the budget deliberately, then arrange your zoom ranges so the budget is rarely reached.

Validation and Error-Handling Matrix

Condition Root cause Detection Remediation
Features vanish at some zooms only Automatic dropping to fit the budget Missing features cluster in dense tiles Set per-feature zoom ranges from a computed rank
Layer name unexpected Layer derived from the input file name Layer named after the file, not the data Name each layer explicitly on its input
Attributes missing from tiles Attribute limit reached, or types inconsistent Some features carry a property, others do not Normalise property types before export
Tiles enormous at high zoom No maximum zoom set, detail retained fully Archive size grows sharply per level Cap the maximum zoom and rely on overzoom
Polygon coverage has visible seams Adjacent polygons not coalesced Hairlines between same-class parcels Enable coalescing for the coverage layer
Build takes many hours Single-threaded input parsing One core busy, others idle Split input by layer and parallelise the reads
Points overlap illegibly at low zoom No point reduction configured Dense clusters of markers Drop points by rank, or cluster them explicitly

Performance and Scale

Tippecanoe reads its input once into an internal store, then renders each zoom from that store. Two consequences follow.

First, input size dominates the early phase. GeoJSON is verbose; a line-delimited variant streams far better than a single enormous feature collection, and filtering out features you will never render before Tippecanoe sees them is the cheapest optimisation available.

Second, the number of zoom levels dominates the later phase. Each additional maximum zoom level roughly quadruples the tile count. Capping the maximum zoom and letting clients overzoom is almost always the right trade for a base map, and it is a one-flag change that can turn a six-hour build into a ninety-minute one. Tuning Tippecanoe Zoom and Feature Dropping works through both.

How tile count grows with each additional maximum zoom level Five maximum zoom settings with their relative cumulative tile counts for the same area. Building to zoom ten is the baseline. Building to zoom twelve is roughly sixteen times as many tiles. Building to zoom fourteen is roughly two hundred and fifty times. Building to zoom sixteen is roughly four thousand times. Building to zoom eighteen is roughly sixty-five thousand times the baseline, which is why no production base map builds that deep. Each extra zoom level quadruples the work max zoom 10 baseline max zoom 12 about 16x max zoom 14 about 256x max zoom 16 about 4000x max zoom 18 about 65000x Clients scale the deepest available tile, so most of the detail readers think they are getting above zoom 14 is overzoom anyway.
This is the single largest cost decision in a tile build, and it is one flag.

Failure Modes and Gotchas

  • Layer names come from file names by default. A file called export.geojson produces a layer called export, and a style written against transportation then matches nothing.
  • Property types must be consistent. A property that is a number in some features and a string in others produces unpredictable encoding.
  • Dropping is silent. It is reported in the build output, not as an error, so it goes unnoticed in an automated pipeline unless you check.
  • Maximum zoom is not detail. Capping it does not reduce the detail visible when zoomed in beyond it; the client scales the highest tile.
  • Coalescing needs identical attributes. Two adjacent parcels differing only by an unused identifier will not merge.
  • Reserved properties are removed. The tippecanoe: properties control behaviour and do not appear in the output tiles, which is correct but surprising the first time.

Integration Points

Upstream, the export step should compute and attach the rank and zoom-range properties, because that is where the OSM tags are still available — the mapping logic is the same as in Mapping OSM Tags to a Fixed Schema with YAML, with a cartographic target. Downstream, the MBTiles archive is packaged or converted for serving as described in Serving & Invalidating OSM Tiles, and Generating MBTiles from OSM GeoJSON covers the end-to-end run.

Guides in This Topic

Frequently Asked Questions

Why do features disappear at some zoom levels?

Because a tile exceeded the size budget and the dropping stage removed features until it fit. The stage chooses spatially rather than by importance, so in a dense tile the victims are effectively arbitrary. The fix is not to raise the budget but to make the dropping unnecessary: compute a rank per feature during export, map it to a minimum zoom, and write that onto the feature so the tile is the right size before the budget is ever consulted.

Should I set zoom ranges per feature or per layer?

Per feature, wherever you have the information to do so. A layer-wide minimum zoom treats a motorway and a residential cul-de-sac identically, which is exactly the distinction a base map needs. Since the export step still has the OSM tags, that is where the rank should be computed and the zoom range attached; by the time Tippecanoe sees the data the tags may already have been collapsed into a small vocabulary.

What maximum zoom should I build to?

Usually lower than instinct suggests. Each additional level roughly quadruples the tile count, and clients scale the deepest available tile to render beyond it, so the detail loss from capping at a moderate zoom is far smaller than the storage and build-time saving. Build to the zoom at which your data genuinely stops adding detail, and let overzoom handle everything above.

When is coalescing worth enabling?

Whenever a layer is a coverage — land use, administrative areas, blocks of same-class buildings — where adjacent features share attributes and their shared boundaries are drawn twice for no benefit. Merging them removes both the duplicate edges and the hairline seams between them. It is not useful for layers where features are genuinely distinct objects, such as roads or points of interest, and it will not merge features whose attributes differ in any way.

Does Tippecanoe need the input in a particular projection?

It expects geographic coordinates in WGS 84, which is what OSM data already is, and handles the projection into tile space itself. Reprojecting the input first is both unnecessary and harmful, since the tile pyramid is defined in Web Mercator and a pre-projected input will be treated as degrees and land somewhere near the origin of the map.

Up one level: OSM Vector Tiles & Rendering Pipelines.