How to add custom tiles as a QGIS background

This post was made using QGIS 1.8 (or so…). It will not work on 2.4.

Yesterday, Nicholas Duggan (@Dragons8mycat) tweeted about a project he did with his kids over the week-end. He created a “Treasure Map” with them in QGIS using the OpenLayers Plugin that allows you to use OSM, Google, Yahoo or Stamen as a background. I told him that he could have use Mapbox’s Pirate Map as a background which would be cool (that was before discovering that the map zooms from level 2 to 6 which is unsuitable for a local treasure map). For the example, I’ll create a custom map on Mapbox and use it.

FIRST STEP: Read Nicholas’ blog post.

It will tell you how to install QGIS and the OpenLayers Plugin.


SECOND STEP: Create your custom map

Go to and open an account if you don’t have one. It’s free!

1. Pricing  MapBox - Google Chrome_2013-05-29_07-59-48

 Choose the free account. The basic account (at 5$/month, it’s as good as free) gives you the best imagery around. It’s particularly good if your are in the United States or in Europe because you have up to zoom level 19. In Canada, where I live, we have for now up to level 15.


For now, the free account is all you need.

Login into your newly created account and create a new map.



There’s some preset background that are really good from which you can start (I can choose the satellite background because I have the basic account).

NewMap2 And then, you can modify it.

PresetYou can use any of the predefined color scheme to create a distinctive look (like that orange palette) or keep it like that.


For the tutorial, I’ll use a customized one, so I’ll click on the second tab “Customize”. There, you can adjust the color of almost everything on the map. Let say we want to create a map for the upcoming Father’s Day so we’ll create a map in the palette of our father’s favorite brown jacket. We tweak the colors a little bit to create a nice ugly brownish map.

CustomThat way, it will be easy to see that the map inserted in QGIS in the end is really the one we created 😉  Click “Save” and then “Publish”.

PublishCopy the link at the top in your favorite text editor.


THIRD STEP: Modify the OpenLayers Plugin.

Go to the folder where your QGIS plugins are installed and navigate to the OpenLayers Plugin. It should be: “C:\Users\your_user_name\.qgis\python\plugins\openlayers_plugin”

Open the file file “” in your favorite text editor and find the lines where all the available backgrounds are listed.

OpenlayerPluginPyCopy and paste the last line and modify the last part so it will contain information about your custom background. I put “Mapbox Custom Brownish”. Use a .png that I created from mapbox logo (the .png should be in the same folder as your .py file). Give the name “mapbox_brown.html” to the page that will be displayed as a background in QGIS (we are getting there just now). Save and close.

Now, navigate to the “html” subfolder that is in the “..\plugins\openlayers_plugin” folder (that would be “C:\Users\fgoulet\your_user_name\python\plugins\openlayers_plugin\html”. Copy and paste one of Stamen’s html file. Don’t use Google’s or Yahoo’s because they reference Google’s and Yahoo’s map api. The Stamen background are using all OpenLayers’ .js and .css which is what we want. I use “stamen_terrain.html”.

Go to line 30ish where there’s the declaration of a variable called “apple”.

ToChangeand change the first string to “Mapbox Custom Brownish” or whatever name you gave your map. In place of “http/”, copy the link you copied earlier, without the last part “page.html”, but keep the “/${x}…” till the end of the line. That’s the reference to your tiles in your account. You should have something like “${z}/${x}/${y}.jpg”.


Save and close.


FOURTH STEP: Add your tiles as a background.

Open QGIS. Click Plugins>OpenLayers plugin and you’ll see at the end the name of your map. Click on it!


Voilà! Your custom map appears in the background. Add your own data if you want. I work for a transit agency so I’ll add our train lines for the example. You can even change the projection. The tiles will be automatically reprojected.

QuantumGIS_final Here you go. You can now add as many custom background as you want. You could use TileMill to create custom maps, upload them on your mapbox account and use them as a background.

Now, if I could just find the time to create a local Pirate map…








This entry was posted in Uncategorized. Bookmark the permalink.