Skip to content
Go to file


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

Note well: this project is no longer actively developed. Issues and pull requests will be attended to when possible, but delays should be expected.


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 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 "z/000/000/x/000/000/y.png"''',
                        and "zyx" which is the format vips dzsave --layout google uses.
                        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=""
  --do_compression      Do mbtiles compression
  --silent              Dictate whether the operations should run silently

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)
You can’t perform that action at this time.