Skip to main content

An importer and exporter for MBTiles

Project description

# MBUtil

MBUtil is a utility for importing and exporting the [MBTiles]( format,
typically created with [MapBox]( [TileMill](

Before exporting tiles to disk, see if there's a [MapBox Hosting plan](
or an open source [MBTiles server implementation](
that works for you - tiles on disk are notoriously difficult to manage.

## Installation

Git checkout (requires git)

git clone git://
cd mbutil
./mb-util -h

# then to install the mb-util command globally:
sudo python install
# then you can run:

Python installation (requires easy_install)

easy_install mbutil
mb-util -h

## Usage

mb-util [command] [options] file|directory [file|directory ...]


Export an mbtiles database to a directory of files:
$ mb-util --export world.mbtiles tiles

Import a directory of tiles into an mbtiles database:
$ mb-util --import tiles world.mbtiles

Create an empty mbtiles file:
$ mb-util --create empty.mbtiles

Execute commands on all tiles in the mbtiles file:
$ mb-util --process --execute "COMMAND ARGUMENTS" [--execute "SECOND COMMAND"] world.mbtiles

Merge two or more mbtiles files (receiver will be the first file):
$ mb-util --merge receiver.mbtiles file1.mbtiles [file2.mbtiles ...]

Fill a mbtiles database with a given tile image
$ mb-util --fill --min-zoom=7 --max-zoom=12 world.mbtiles transparent.png

Check if a mbtiles file contains all tiles at a specific zoom level:
$ mb-util --check --zoom=7 world.mbtiles

Test tiles with a command, print tile coordinates for non-zero return values
$ mb-util --test --execute "COMMAND ARGUMENTS" world.mbtiles

Compact a mbtiles file by eliminating duplicate images:
$ mb-util --compact world.mbtiles

Convert tile coordinates and bounding boxes:
$ mb-util --convert="13/4328/2861"
$ mb-util --convert="10.195312,47.546872,10.239258,47.576526" --min-zoom=12 --max-zoom=13

-h, --help show this help message and exit

These are the commands to use on mbtiles databases

-e, --export Export an mbtiles database to a directory of files. If
the directory exists, any already existing tiles will
be overwritten.
-i, --import Import a directory of tiles into an mbtiles database.
If the mbtiles database already exists, existing tiles
will be overwritten with the imported tiles.
-m, --merge Merge two or more databases. The receiver will be
created if it doesn't yet exist.
-p, --process Processes a mbtiles databases. Only usefull together
with one or more --execute.
--check Check the database for missing tiles.
--test Test every tile with the given command, print the tile
coordinate if the command returns anything non-zero.
--fill Fill a mbtiles database with tiles where
it doesn't already contain a tile. Only usefull with
--min-zoom/--max-zoom and --tile-bbox/--bbox.
--compact Eliminate duplicate images to reduce mbtiles filesize.
--create Create an empty mbtiles database.
--convert=CONVERT Convert tile coordinates 'y/x/z' to bounding box
'left,bottom,right,top' or vice versa.

--execute=COMMAND Commands to execute for each tile image. %s will be
replaced with the file name. This argument may be
repeated several times and can be used together with
--flip-y Flip the y tile coordinate during
Minimum zoom level for
Maximum zoom level for
--zoom=ZOOM Zoom level for
(Overrides --min-zoom and --max-zoom)
Minimum numerical timestamp for --export/--merge.
Maximum numerical timestamp for --export/--merge.
--bbox=BBOX Bounding box in coordinates 'left,bottom,right,top'
Bounding box in tile coordinates
'left,bottom,right,top' (10,10,20,20). Can only be
used with --zoom.
--no-overwrite don't overwrite existing tiles during
--revert-test For --test, print the tile coordinates if the command
returns zero.
--auto-commit Enable auto commit for --merge/--import/--process.
--synchronous-off DANGEROUS!!! Set synchronous=OFF for the database
--use-wal-journal Use journal_mode=WAL for the databases (default is
Runs some basic checks (like --check) on mbtiles
before merging them.
DANGEROUS!!! After a --merge or --export, this option
will delete all the merged/exported tiles from the
(sending) database. Only really usefull with --min-
zoom/--max-zoom or --zoom since it would remove all
tiles from the database otherwise.
DANGEROUS!!! If a tile vanishes during --execute then
delete it also from the database or ignore it during
Pool size for processing tiles with --process/--merge.
Default is to use a pool size equal to the number of
--tmp-dir=TMP_DIR Temporary directory to use for --execute.
--vacuum VACUUM the mbtiles database after
--analyze ANALYZE the mbtiles database after
--progress Print progress updates and keep them on one line
during --import/--merge/--export/--compact/--process.
-q, --quiet don't print any status messages to stdout except
-d, --debug print debug messages to stdout (exclusive to --quiet).

## Special considerations

* All mbtiles databases must be on the same host as the mb-util binary if you want to use the WAL locking mode.
* Using --synchronous-off is dangerous since your database might get corrupted.
* Use --tmp-dir=/dev/shm on Ubuntu to place temporary files on a ram disk.
* Use --use-wal-journal if you want to udpate a database which is at the same time used for reading.
* --auto-commit will disable transactions and therefore most probably slow down any insert operations to the database.

## Requirements

* Python `>= 2.6`
* SQLite `>= 3.7.0`

## Metadata

mb-util imports and exports metadata as JSON, in the root of the tile directory, as a file named `metadata.json`.

"name": "World Light",
"description": "A Test Metadata",
"version": "3"

## Testing

This project uses [nosetests]( for testing. Install nosetests
and run


## License

BSD - see

## Authors

- Tom MacWright (tmcw)
- Dane Springmeyer (springmeyer)
- Mathieu Leplatre (leplatrem)
- Thomas Rasch (trasch)

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

umimbutil-0.1.0.tar.gz (18.5 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page