Opening a vector layer, such as a the countries dataset contained in the Natural Earth geopackage, using the GUI is as simple as double-clicking it in the data source manager or drag-and-dropping it into the map window:

If we want to do the same thing using Python, we need to know the exact source of the layer data. This information can be found in the layer properties. Note how the source contains the path to the geopackage as well as information about the country layer’s layer name:

If you are not using QGIS 3 yet, the above dialog will look different but it contains the same information.

Copy the source information, we’ll need it! Note the forward slashes / in the file path. Even on Windows, you should use forward slashes instead of backward slashes to avoid errors.

Let’s get back to the Python console. As mentioned in the Hello world example, the interactive Python console immediately executes code we input once we press Enter. Since we are planning to write more than one line of code in this example (two actually), it will be convenient to use the built-in code editor instead of the interactive console. It’s basically a text editor that lets you work on multiple lines of code until you’re happy and want to execute it all at once. The Show Editor button in the Python console opens the code editor panel:

Now it’s time to use the source information we copied from the layer properties. We create a variable called uri and store the source information string in it. We choose to call the variable uri – we could call it anything we like. Then we can use the uri as one of three parameters of the iface.addVectorLayer function:

uri = "E:/Geodata/NaturalEarth/vector_v4/natural_earth_vector.gpkg_v4.1.0/packages/natural_earth_vector.gpkg|layername=ne_10m_admin_0_countries"
iface.addVectorLayer(uri, "countries", "ogr")

If you press the Run Script button, the code will be executed and QGIS will load the layer into the current project. Congratulations!

Ok that’s great but what’s this iface thing? iface is an object belonging to QGIS – something that has properties and behaviors we can use to interact with QGIS. iface is a very important object in QGIS because without it, we could not interact with QGIS or any layers loaded in our project. In our code we’ve told the iface object to execute one of the functions which is associated with it – in this case the addVectorLayer function. Different objects are associated with different functions. Just to make life confusing, functions are sometimes called methods. You can find a list of all functions in the official PyQGIS documentation.  You’ll see that addVectorLayer is listed in the documentation as a method belonging to iface with the following description:

addVectorLayer(self, vectorLayerPath: str, baseName: str, providerKey: str) → QgsVectorLayer

This description provides us with some information about the parameters of addVectorLayer:

1. The first parameter is self. This is a default parameter that is required when writing many Python functions but it does not have to be provided when calling the function. Therefore, we can ignore it and skip ahead to the second parameter:
2. The description shows that vectorLayerPath should be a string (str). In our example above, we used the string variable uri to provide this input.
3. The next parameter is a string called baseName. This will be the layer name that is displayed in the layer list and we can pick a value freely.
4. Finally, the last parameter is a string called providerKey. For most vector data formats (including Geopackage and Shapefile) the provider of choice will be OGR. Other vector provider keys include “postgres”, “delimitedtext”, “gpx”, “spatialite”, and “WFS”. (See also: PyQGIS Developer Cookbook: Loading Layers)

The last part of the description (→ QgsVectorLayer) means that the function returns the created QgsVectorLayer object. Don’t worry about this now, we will get to that in the next examples, promised!

Don’t forget to save! Since scripts are not automatically saved when exiting QGIS, you should make sure to manually save the script using the save button in the editor.

These are the basics of using the code editor to write multiple lines of code that can be executed all at once. You also saw how to interpret a function description from the official PyQGIS documentation.

Next: Viewing vector layer attributes

PyQGIS 101 is a work in progress. I’d appreciate any feedback, particularly from beginners!