skip to navigation
skip to content

Not Logged In

umimbutil 0.1.0

An importer and exporter for MBTiles

# 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)
File Type Py Version Uploaded on Size
umimbutil-0.1.0.tar.gz (md5) Source 2013-01-30 18KB
  • Downloads (All Versions):
  • 4 downloads in the last day
  • 31 downloads in the last week
  • 177 downloads in the last month