PMTiles-MBTiles-Util

PMTiles-MBTiles-Util is a utility for importing, exporting, and converting between the MBTiles and PMTiles archive formats, as well as flat directory tile structures on disk. It provides the pmtiles-mbtiles-util command.

⚙️ 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

pip install pmtiles-mbtiles-util

The name differs from the upstream project it forks. mbutil on PyPI belongs to the original, now-archived Mapbox project, and PyPI rejects mb-util too as being too similar to it. The command and the import package match the distribution, so nothing is shared with the original:

From source

git clone https://github.com/TechIdiots-LLC/pmtiles-mbtiles-util.git
cd pmtiles-mbtiles-util

# Install the pmtiles-mbtiles-util command globally
pip install .

Docker

PMTiles-MBTiles-Util is also available as a Docker image. See DOCKER.md for usage instructions.

🛠 Usage

pmtiles-mbtiles-util [options] <input> <output>

Quick Examples

Options

💎 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
pmtiles-mbtiles-util --do_compression --hash_type sha256_truncated ./my_tiles world.mbtiles

Hash Types

⚡ 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 pmtiles-mbtiles-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

• PMTiles Project — The cloud-native, single-file tile format.
• PMTiles Documentation — Reference for the PMTiles ecosystem.
• MBTiles Spec — The SQLite-based tile container specification.

🧪 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

📄 License

BSD — See LICENSE.md for details.

👥 Authors

• Andrew Calcutt (acalcutt) — Current Maintainer
• Tom MacWright (tmcw) — Original Creator
• Dane Springmeyer (springmeyer)
• Mathieu Leplatre (leplatrem)