mbmerge
Incrementally merge PNG and WebP raster MBTiles with alpha compositing, bounded batches, parallel image processing, and a single SQLite writer. Resume safely after interruption without applying committed translucent layers twice.
Installation
pipx install mbmerge
mbmerge --version
Alternatively, install with python -m pip install mbmerge in a virtual environment. Requires Python 3.11+, SQLite 3.35+, and Linux/macOS. Windows is not supported. Pillow is installed as a dependency; WebP support is required when reading or writing WebP.
Usage
mbmerge merge --input-dir /data/inputs --output /data/merged.mbtiles
# PNG output, including transparent overlaps:
mbmerge merge --input-dir /data/inputs --output /data/merged-png.mbtiles \
--output-format png --png-compress-level 3
mbmerge status --output /data/merged.mbtiles
mbmerge verify --output /data/merged.mbtiles --decode
Run the same merge command again to resume. Completed unchanged sources are skipped; new sources are appended. Later sources are composited over earlier sources at shared tile coordinates. Different tile coordinates remain distinct in the combined archive.
Input and operating limits
Inputs must be immutable, offline, flat MBTiles tables with a unique ascending index on (zoom_level,tile_column,tile_row). Coordinates are Web Mercator/TMS. Tiles must have the same square dimensions; the default is 512 px (--tile-size 256 for 256 px sources). Static WebP and PNG up to 8 bits per channel are supported; mixed inputs are converted to a uniform output format. New outputs default to lossless WebP. Animations, 16-bit PNG, JPEG, vector tiles, normalized layouts and WAL-mode sources are rejected.
An existing output created by mbmerge is extended. For an MBTiles archive created by another tool, use it as the first input and choose a new output. Changed previously imported sources are rejected: restore their exact original bytes or rebuild. Keep all recorded source paths available. The output format and active encoder settings are fixed on resume.
Batches, submitted jobs, blob sizes and image dimensions are bounded. The batch budget is not a hard cap on total process RSS. Use local SQLite-compatible storage and avoid long output-reader transactions during importing. Bounds use declared source extents or full tile footprints, without alpha-edge cropping. A real 1 TB import has not been tested.
Use mbmerge merge --help for all limits and options. python -m mbmerge is also supported.
License
MIT License. Copyright (c) 2026 mbmerge contributors.
1 maintainer
Metadata
1 maintainer
Release files for mbmerge 1.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mbmerge-1.1.0.tar.gz | 175.8 kB | With provenance | Details for mbmerge-1.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mbmerge-1.1.0-py3-none-any.whl | Python 3 | none | any | Details for mbmerge-1.1.0-py3-none-any.whl |
Total release size: 197.0 kB
Release files / mbmerge-1.1.0.tar.gz
| Download URL | mbmerge-1.1.0.tar.gz |
|---|---|
| Size | 175.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9e76435242dca95dda44e8373b02986be6265fb227fefccbecc797792ca9affd
|
|
BLAKE2b-256 checksum How to use checksums |
35c53a3f520841acdec5d069fb3db5fe30b8bb5aec6c81d9dcc8f8e9fc9bf60f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logRelease files / mbmerge-1.1.0-py3-none-any.whl
| Download URL | mbmerge-1.1.0-py3-none-any.whl |
|---|---|
| Size | 21.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
109db07a02bbd33d3f76a8ac5ce7b7aba344773475ea8791404d822fe6c29186
|
|
BLAKE2b-256 checksum How to use checksums |
9fd88e0a525ecca4a1b091e192bd60ea6119cb6b33a32bdf7445da6da2b68229
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logSecurity for mbmerge 1.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for mbmerge-1.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
