Skip to content

README.md

Latest commit

 

History

History
150 lines (102 loc) · 5.59 KB

README.md

File metadata and controls

150 lines (102 loc) · 5.59 KB

MBUtil

MBUtil is a utility for importing, exporting, and converting between the MBTiles and PMTiles archive formats, as well as flat directory tile structures on disk.

Important

This repository is a fork of the original mapbox/mbutil, which was archived on March 10, 2026. It is now maintained under TechIdiots LLC and continues to be distributed under the original BSD license.

⚙️ Capabilities

  • Format Conversion: Directly convert .mbtiles to .pmtiles and vice versa.
  • MBTiles Support: Full import/export support for the MBTiles SQLite-based tile archive format.
  • PMTiles Support: Full import/export and direct conversion support for the PMTiles single-file tile archive format.
  • Disk Export: Extract tiles from an archive to a standard directory structure (XYZ, TMS, etc.).
  • Disk Import: Pack a directory of tiles into a single portable archive.
  • Deduplication: Use hash-based compression to reduce file sizes for repetitive maps (e.g., oceans or vector data).

📦 Installation

This project uses git submodules for PMTiles support. The --recursive flag is required.

git clone --recursive https://github.com/TechIdiots-LLC/mbutil.git
cd mbutil

# Install the mb-util command globally
pip install .

Note: If you already cloned the repo without submodules, run git submodule update --init inside the folder.

Docker

MBUtil is also available as a Docker image. See DOCKER.md for usage instructions.

🛠 Usage

mb-util [options] <input> <output>

Quick Examples

Action Command
Convert MBTiles to PMTiles mb-util world.mbtiles world.pmtiles
Convert PMTiles to MBTiles mb-util world.pmtiles world.mbtiles
Extract to Directory mb-util world.pmtiles ./tiles_dir
Import from Directory mb-util ./tiles_dir world.mbtiles
Dump Metadata mb-util world.pmtiles dumps

Options

Option Description
-h, --help Show help message and exit
--scheme=SCHEME Tiling scheme: xyz (default), tms, wms, zyx, ags, gwc
--image_format=FORMAT Tile format: png, jpg, webp, pbf, mvt, mlt
--do_compression Enable hash-based tile deduplication when writing to MBTiles (has no effect for PMTiles or disk output)
--hash_type=TYPE Algorithm for deduplication: fnv1a (fastest, default), sha256, sha256_truncated, md5
--silent Disable progress logging for faster execution

💎 Tile Deduplication

Deduplication behaviour varies by output format:

  • MBTiles output: Use --do_compression to enable hash-based deduplication. Identical tiles are stored only once with internal references, which can significantly reduce file size for repetitive maps (e.g. ocean tiles, empty areas, vector data).
  • PMTiles output: Deduplication is built into the PMTiles format and happens automatically. --do_compression is not needed and has no effect.
  • Disk output: No deduplication — each tile is written as an individual file.
# Deduplicate when writing to MBTiles
mb-util --do_compression --hash_type sha256_truncated ./my_tiles world.mbtiles

Hash Types

Hash Type Bits Speed Best For
fnv1a (default) 64 Fastest General use
sha256_truncated 64 Medium Balanced performance
sha256 256 Medium Maximum collision resistance
md5 128 Fast Legacy compatibility

⚡ Performance & Large Files

  • Deduplication: Use --do_compression when writing to MBTiles to reduce file size for repetitive content. PMTiles handles deduplication automatically.
  • Silent mode: Use --silent to skip progress logging for a small speed boost.
  • Temporary Storage: When converting to PMTiles, the utility writes a temporary file during conversion. By default this goes to /tmp, which on some Linux systems is RAM-backed (tmpfs). For very large files, redirect it to a physical disk:
TMPDIR=/mnt/external_drive/tmp mb-util world.mbtiles world.pmtiles

The temp file grows to roughly the same size as the output PMTiles archive and is deleted automatically when conversion completes.

🔗 Specifications & Resources

🧪 Testing

Tests use Python's built-in unittest and are compatible with both pytest (recommended) and nosetests.

# Using pytest (recommended)
pip install pytest
pytest test/

# Using unittest directly
python -m unittest discover test/

# Using nosetests (legacy)
pip install nose
nosetests

Test files:

  • test/test.py — MBTiles import/export tests
  • test/test_pmtiles.py — PMTiles conversion and roundtrip tests (requires PMTiles submodule)

📄 License

BSD — See LICENSE.md for details.

👥 Authors