NZ Techonverse: Install mb-util on Debian

First published on NZ Techonverse

I use a Python script called mb-util to build the mbtiles files for the NZ Rail Maps webmaps site. It takes the raw tiles and builds what is effectively a SQLite database that encapsulates the millions of little tiles into one file, which is much easier to handle for file storage and uploading, although slightly slower to stream on a web server.

mb-util can be obtained from the GitHub site. There is a multi-step process to follow to get it installed into a standard location so that it can just be typed as a standalone command in Bash:

  • First of all download from – click on that green Code button. ( or use the command line: git clone git:// )
  • Go into the mbutil directory
  • To install needs a python script and additional Python libraries such as setuptools or pip. If you haven’t got those:
  • Go to
  • Click on the link “Installation Instructions”
  • Follow the instructions in that screen. In particular, if you don’t have pip installed, download a script called from
  • Run the script using the python3 command i.e. python3
  • This will download setuptools, pip and wheel to your system
  • Use the command below to ensure you have the tools installed and they are the most up to date:
    python3 -m pip install –upgrade pip setuptools wheel
  • Finally you can install mbutil by changing into the directory where you downloaded it to (e.g. ~/mbutil) and running this command: python3 install
  • Then check you can run commands by typing mb-util, it should output the help screen.

When using mb-util I normally use –silent and –do_compress as well as image_format as appropriate. do_compress enables mbtiles compression, which can save a lot of file space where there are lots of identical tiles in your source. The most obvious type of tile duplication you are going to see is tiles that are completely blank, and there are a lot of these in the NZ Rail Maps webtiles because the current build process captures relatively large rectangular areas that have a lot of white space around the actual narrow rail corridor. At the moment using the tile compression capability of mb-util is the easiest way to eliminate the tile wastage for a lot of the tile sources that only capture rail tracks or location symbols that have lots of white space around them in the layers. The Non Rail overlay and topographic base layers are examples of where there is less white space and thus, less compression likely to happen as the data in these layers covers areas outside the rail corridor so there will be less compression possible with these layers.

In order to help streamline the process of building tiles I am planning to write a build script that just automates the steps of using mbutil and makes it easier for me by just letting me type one simple command to build the mbtiles files.

Read More