How to Add a Map from Mapbox to QGIS

Caitlin Dempsey


Mapbox is a provide of a service that lets you create and serve custom online web maps.  Users can customize any of the standard map styles and upload their own data to add to those maps.  Low volume users can take advantage of the free plan level to access satellite and street base maps to build upon.

These map styles can also be loaded into the free and open source desktop GIS software program, QGIS.  This tutorial will show you how to take a map style you have created in Mapbox and load it into a QGIS session.  You can also view a video version of this tutorial at the bottom of this page.

This tutorial requires that you have an existing Mapbox account and have set up at least one map style.  To get started with Mapbox, sign up for free.

Create a Map Style in Mapbox

The first thing you will need to do in Mapbox is to create a map style in your studio.  To familiarize yourself with how to do that, visit the tutorial page from Mapbox on creating styles.  If you are just interested into a predesigned basemap, then just select one of the style templates.  Type in the name for your new map style.

Free weekly newsletter

Fill out your e-mail address to receive our newsletter!

Either customize the map style in the editor or you can opt to use the default template style.  From your styles page, click on the menu option for the style you want to load into QGIS.

Select the first option, “Share, develop & use”.  Next, scroll down to the bottom of the page to the section that says “Use with WMTS service”.  Click the toggle button to select QGIS.  Then select and copy the URL provided in the WMTS endpoint box.  You will need this URL when you open up QGIS.

Loading the Mapbox Style in QGIS Using WMTS Service

Now open up QGIS.  On the far left are icons for loading different data types into QGIS.  Select the globe icon to load a layer from a WMTS Server.

Make sure the Layer option is highlighted and then select “New”. Under Connection Details type in a name for the service (e.g. Mapbox) and then paste in the URL you copied from Mapbox. Hit OK.

This will take you back to the “Add Layer(s) from a WM(T)S Server GUI.  You should notice that the “Connect” button is now highlighted.

Click on the “Connect” button and you should see your map style name from Mapbox listed. Highlight this entry (it should convert to a shaded blue) and type the layer name that you want for this map style to show up under in the QGIS layers panel.  Then hit add and then close.

Your Mapbox style will now be added to the layers panel in QGIS.

It will load as a flat layer so you can pan and zoom but you can’t turn individual layers on and off from the style like you can do from Mapbox Studio.  All of the styling behaviors such as scale dependent rendering will be preserved.  For example, as you zoom in, you will see style changes and labeling as you change the scale.

You can also load other GIS data on top of the Mapbox style and change the projection.  In this example, a shapefile of ocean debris landings was added.  Since the data covers an area of the Pacific between Japan and the western United States, I have reprojected the data from Mapbox’s default Web Mercator map projection  to a Pacific-centric orientation using the WGS 1984 PDC Mercator projection.

Video Tutorial: How to Add a Map from Mapbox to QGIS

YouTube video

More QGIS Tutorials

Photo of author
About the author
Caitlin Dempsey
Caitlin Dempsey is the editor of Geography Realm and holds a master's degree in Geography from UCLA as well as a Master of Library and Information Science (MLIS) from SJSU.