Importer and Exporter of MBTiles
Python Shell
Latest commit e49a223 Sep 30, 2016 @tmcw tmcw committed on GitHub Merge pull request #74 from himaps/master
Add support for tiles generated by geowebcache (scheme=gwc).


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.

Build Status


Git checkout (requires git)

git clone git://
cd mbutil
# get usage
./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


$ mb-util -h
Usage: mb-util [options] input output

    Export an mbtiles file to a directory of files:
    $ mb-util world.mbtiles dumps # when the 2nd argument is "dumps", then dumps the metatdata.json

    Export an mbtiles file to a directory of files:
    $ mb-util world.mbtiles tiles # tiles must not already exist

    Import a directory of tiles into an mbtiles file:
    $ mb-util tiles world.mbtiles # mbtiles file must not already exist

  -h, --help            show this help message and exit
  --scheme=SCHEME       Tiling scheme of the tiles. Default is "xyz" (z/x/y),
                        other options are "tms" which is also z/x/y but uses a
                        flipped y coordinate, and "wms" which replicates the
                        MapServer WMS TileCache directory structure
                        The format of the image tiles, either png, jpg, webp
                        or pbf
                        Option to control JSONP callback for UTFGrid tiles. If
                        grids are not used as JSONP, you can remove callbacks
                        specifying --grid_callback=""

Export an `mbtiles` file to files on the filesystem:

    mb-util World_Light.mbtiles adirectory

Import a directory into a `mbtiles` file

    mb-util directory World_Light.mbtiles


  • Python >= 2.6


MBUtil 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"


This project uses nosetests for testing. Install nosetests:

pip install nose


easy_install nose

Then run:


See Also


BSD - see


  • Tom MacWright (tmcw)
  • Dane Springmeyer (springmeyer)
  • Mathieu Leplatre (leplatrem)