Connect QGIS to CARTO using an OGR VRT file.

This post may describe functionality for an old version of CARTO. Find out about the latest and cloud-native version here.

You can use OGR to move data into and out of CARTO. And you can use QGIS to view and edit layers supported by OGR. So it would stand to reason that you should be able to use QGIS to view and edit CARTO data directly: but how?

Here's one quick and dirty way to connect QGIS to your CARTO layers.


First  you need to make sure QGIS can access your layers using a CARTO master API key. The OGR driver reads system tables  so it requires the master key to operate.


QGIS Environment Variables


  • Open the QGIS Preferences menu.
  • Navigate to the System panel.
  • Scroll to the Environment area.
  • Add a new environment variable  CARTO_API_KEY.
  • Put your API key in the "Value" field.
  • Press the OK button.
  • Shut down QGIS and re-open it to bring the new environment variable into effect.

Now we need to record the connection information OGR will need to access CARTO  and put that information into a "VRT" file.

VRT File

A VRT file defines connection information and layer names so that an OGR client (like QGIS) can easily connect to a source without reading a lot of metadata. Here's an example minimal VRT file with two layers defined:

    <OGRVRTLayer name="subway_stations">
    <OGRVRTLayer name="streets">
  • This file reads CARTO tables nyc_subway_stations and nyc_streets and exposes them to QGIS using the names "subway_stations" and "streets".
  • The <LayerSRS> should always be EPSG:4326  as that is the system CARTO always uses.
  • The <SrcDataSource> is of the form "Carto:username"  where "Carto" tells OGR what driver to use and the "username" is your CARTO user name. For multi-user accounts  "username" must be the user name and not the organization name.
  • The <GeometryType> is optional  but ensures that OGR knows whether the input layer is a point  line or polygon.    

You can test your VRT file using the ogrinfo utility. You should be able to run ogrinfo and get a listing of layers back  for example:

# ogrinfo carto.vrt 

INFO: Open of `carto.vrt'
      using driver `OGR_VRT' successful.
1: subway_stations
2: streets

Once you have a working VRT file  you can add the file as a layer in QGIS!

Adding the Layer

After you've set up your API key and authored your VRT file  go to Layer > Add Layer > Add Vector Layer… in QGIS  and select your VRT as the source vector dataset  using a "File" source type.


QGIS Vector File Source


If your VRT includes multiple layer definitions  you'll be asked to select which layers (or all of them) that you want to add. Then you should be able to see the data draw on your QGIS map!


QGIS Vector File Source


Working with the Layers

Once you have loaded the layers  they work just like any other QGIS layer:

  • You can style them any way you like.
  • You can include them in printed output.
  • You can reproject the map and see them in other projections.
  • You can edit them (yes  really!)    
  • You can include them in QGIS analyses.

Since you are editing the live data in CARTO  it's possible to apply edits in QGIS and see your published CARTO maps update in real time!