Output Tuning | geolith Builder docs

Max Zoom Levels

The --max-zoom option controls the maximum detail level. Each additional zoom level roughly quadruples the number of tiles.

Max Zoom	Approx. Tile Count (planet)	Typical Output Size	Use Case
6	~5,000	~50 MB	World overview, continental boundaries
8	~85,000	~500 MB	Country-level detail
10	~1.3 million	~5 GB	Regional roads and land use
12	~22 million	~30 GB	City blocks visible
14	~350 million	~200 GB	Full detail, individual buildings
15	~1.4 billion	~500+ GB	Maximum detail (large output)

Info

Output sizes are approximate and vary by region density. Urban areas produce more tiles than oceans due to deduplication of empty tiles.

Choosing the Right Zoom Level

Zoom 14 is the default and recommended for most use cases. It provides full building-level detail without excessive output size.
Zoom 10–12 is a good choice for overview maps or when storage is limited.
Zoom 15 should only be used when maximum detail is required and storage is not a concern.

Disk Space Estimates

Plan for these storage requirements:

Component	Size Estimate	Notes
Input data (Overture)	~200 GB (planet)	Downloaded GeoParquet files
Temporary sort files	~1.5× input size	LZ4 compressed, stored in `--tmpdir`
Output PMTiles	~1× input size	After deduplication (30–50% savings)
Total disk needed	~3.5× input size	Input + temp + output

For a full planet build at zoom 14:

Input:  ~200 GB
Temp:   ~300 GB
Output: ~200 GB
─────────────────
Total:  ~700 GB free disk space recommended

Warning

Ensure your --tmpdir has enough space for temporary files. Running out of disk during the sort phase will cause the build to fail.

Reclaiming Source Data During the Build

By default every Overture Parquet file stays on disk for the whole read, so peak usage is input + sort chunks. On a disk-constrained machine that is the difference between a build completing and a build failing with ENOSPC.

--reclaim-source-after-read unlinks each Parquet file as soon as its features are safely in the sort chunks:

geolith \
  --data /mnt/data/overture-2026-08-19.0 \
  --output /mnt/data/planet.pmtiles \
  --reclaim-source-after-read

	Peak during the Overture read
Default	input + sort chunks
With `--reclaim-source-after-read`	~input (source shrinks faster than chunks grow)

A file is removed only after both its read and its chunk flush succeed, so a mid-read failure leaves the remaining sources intact. Only Overture inputs are affected — OSM PBF, Natural Earth, shapefiles, and GeoJSON are never touched.

Warning

Reclaimed files are gone: re-download the release to restore them. Restarting a partial build without --resume will need them back.

Thread Count

The --threads option controls parallelism for feature processing (Phase 1).

Threads	Best For
Default (all cores)	Dedicated build machine, fastest processing
Half cores	Shared machine, leaves headroom for other tasks
4–8	Laptops or machines with limited cooling

# Use 8 threads on a 16-core machine
geolith --data ./overture-data --output planet.pmtiles --threads 8

Tip

Memory usage scales roughly linearly with thread count due to per-thread buffers. If you're memory-constrained, reducing threads can help.

Temporary Directory

The --tmpdir option controls where external sort files are written. This is the most I/O-intensive part of the pipeline.

Recommendations:

Use the fastest available disk (NVMe SSD preferred)
Avoid network-mounted filesystems (NFS, SMB)
Avoid the same physical disk as --data if possible (reduces I/O contention)
Ensure 1.5× the input data size is available

# Use a dedicated fast SSD for temp files
geolith \
  --data /mnt/data/overture \
  --output /mnt/data/planet.pmtiles \
  --tmpdir /mnt/fast-nvme/tmp

Optimal Configuration Summary

For a dedicated planet build on a capable machine:

geolith \
  --data /mnt/data/overture-2025.01.0 \
  --output /mnt/data/planet.pmtiles \
  --max-zoom 14 \
  --tmpdir /mnt/nvme/tmp \
  --threads $(nproc)

Setting	Value	Why
`--max-zoom 14`	Full building detail	Good balance of detail and size
`--tmpdir` on NVMe	Fastest sort phase	External sort is I/O bound
`--threads $(nproc)`	All cores	Maximize parallelism
Separate disks for data/tmp/output	Reduced I/O contention	Parallel reads and writes