Getting started with QGIS plugin development in 2022

By the end of reading this post, you should have a working QGIS plugin and a development environment to continue working on it.

With over 2 million worldwide users, it is fair to say QGIS is the most popular open-source desktop GIS. The official QGIS plugin repository has currently over 800 plugins for a wide variety of use cases. Many users use features and functionalities provided by plugins daily, but few dare to dream of creating their own plugin, and those who do often struggle with getting started. While a basic knowledge of Python is required, plugin development does not necessarily need to be overly complicated.

This guide aims to de-mystify the process of getting started with developing your very first QGIS plugin. Even if you have developed plugins before, you may find something useful here. We have already made a guide to plugin development in a previous blog post. Most topics covered there are still relevant and valid, but a few things have changed since then, calling for a slightly updated guide. This guide applies for QGIS 3.24 and 3.22 LTR versions.

This guide assumes you’re using Windows and Visual Studio Code as they are the most popular operating system and likely most popular code editor. However, we always advocate for FOSS (Free and Open Source Software), and it has to be noted many of the steps in this guide do not apply on Linux operating systems, where getting started with plugin development is generally less of a hassle than on Windows.

Creating a new plugin

Note: if you get lost or have difficulties following this guide or developing your plugin, make sure to read the need help-section at the end of this post! Before getting started, you need to install QGIS, we recommend using the LTR version. You also need to install git.

To get started, we recommend using our cookiecutter-qgis-plugin (can also be found from official QGIS plugins) to create your new plugin. By using our tool you get a useful template that is proven to work so you can get started right away without having to write any so-called boilerplate code.

I would recommend creating a separate Python virtual environment to install cookiecutter and its dependencies. Using virtual environments is generally preferred over installing packages globally as isolating environments helps prevent many issues with varying package versions and dependencies.

Create a new folder and open the OSGeo4W shell (it comes with a QGIS installation). Navigate to the folder you just created (cd C:\path\to\project\folder), and enter the command:

%PYTHONHOME%/python.exe -m venv cookiecutter-venv

Running the command may take a few seconds, after which you should have a new directory called cookiecutter-venv. Next, activate the virtual environment with the command:

.\cookiecutter-venv\Scripts\activate

You should now see (cookiecutter-venv) in your command prompt. Now install cookiecutter and pip-tools inside the virtual environment with the commands:

python -m pip install -U pip
pip install cookiecutter pip-tools

Note: if you get an error saying “Can’t connect to HTTPS URL because the SSL module is not available.”, follow the steps in this StackOverflow answer. If you get an “Access is denied” error, simply try running the command again. If the problem persists, open a new OSGeo4W shell as an administrator and try again. Remember to reactivate the virtual environment first!

OSGeo4W Shell modifies the PATH variable. In practice, this means you likely get the following error when trying to run git commands in OSGeo4W Shell even if Git is installed:

To fix this, temporarily add git to PATH manually, before running the cookiecutter command:

set PATH=%PATH%;C:\Program Files\Git\cmd
cookiecutter https://github.com/GispoCoding/cookiecutter-qgis-plugin

If this is your first time running the cookiecutter-qgis-plugin wizard, you can simply hit enter to accept the default values. If you intend to keep using VS Code, you can answer yes to add_vscode_config. You now have a working QGIS plugin inside the my-qgis-plugin directory!

Note: if you still get an error saying “‘git’ is not installed”, make sure the PATH variable is set correctly (see above) and running the command git does not cause an error message.

Setting up the development environment

So far we have managed to create a new plugin based on the cookiecutter-qgis-plugin template. Now it’s time to set up the development environment so VS Code can provide useful autocompletions and does not constantly nag you about missing libraries.

In OSGeo4W Shell, navigate to the newly created plugin directory (my-qgis-plugin if you chose the default values) with cd. We are going to create and activate a brand new virtual environment called .venv that is used just for our plugin, so run the following commands:

deactivate
%PYTHONHOME%/python.exe -m venv --system-site-packages .venv
.\.venv\Scripts\activate

Note: we now have two separate virtual environments, the first one where we installed cookiecutter, and the second that we are going to use for plugin development. Make sure not to mix these up!

Using the flag --system-site-packages ensures the necessary PyQGIS libraries are installed to the new virtual environment. The cookiecutter template includes a requirements-dev.txt that includes some useful libraries and tools e.g. for writing unit tests with pytest. Install these by running the command:

pip install -r requirements-dev.txt

Note: if you get an error with permissions, simply try running the command again. If the problem persists, open OSGeo4W Shell again as an administrator, reactivate the .venv virtual environment and try again.

You can ensure the install was successful by running the command pip freeze. This prints a list of packages installed in the virtual environment, which should include e.g. pytest and pytest-qgis.

Finally it’s time to start VS Code and open our plugin folder (by default my-qgis-plugin). First let’s instruct VS Code to use the .venv virtual environment that we have created. Hit Ctrl+Shift+P, type in “Python select interpreter” and hit enter. Pick the option with the path .\venv\Scripts\python.exe and hit enter:

Use VS Code to create two new files. First, create a file in the .venv directory called qgis.pth. Create another file inside the .venv\Lib\site-packages directory called sitecustomize.py.

Open the new qgis.pth file and type in the path of your QGIS Python directory. This varies by system. Common locations include C:\OSGeo4W\apps\qgis-ltr\python and C:\Program Files\QGIS <version>\apps\qgis-ltr\python. Make sure you use a path that actually exists on your system! In my instance the correct path was C:\Program Files\QGIS 3.24.2\apps\qgis\python.

Note: at this point, it’s useful to make a note of the base path of your QGIS installation. In my case it is C:\Program Files\QGIS 3.24.2, i.e. the full path without \apps\qgis\python.

Edit the sitecustomize.py file created earlier and copy in the following lines (notice the use of / instead of \ in file paths):

import os
os.add_dll_directory("C:/Program Files/QGIS 3.24.2/bin")
os.add_dll_directory("C:/Program Files/QGIS 3.24.2/apps/qgis/bin")
os.add_dll_directory("C:/Program Files/QGIS 3.24.2/apps/Qt5/bin")

Replace C:/Program Files/QGIS 3.24.2 with the base path of your QGIS installation, e.g. C:/OSGeo4W or C:/Program Files/QGIS <version>. Simply look at what directories exist on your filesystem. Note that you may also need to change /apps/qgis/bin to /apps/qgis-ltr/bin.

Save your changes to both files and restart VS Code for good measure. Open the plugin.py file (by default inside the myqgisplugin directory). If everything went well, you should see no errors or squiggly lines at the top of the file that contains all of the imports:

If that’s the case, congratulations, you have set up a fully functional plugin development environment!

What next?

By default cookiecutter-qgis-plugin clones a directory called qgis_plugin_tools inside your plugin directory. QGIS plugin tools is a helpful library that contains many functionalities that are useful when developing plugins.

After setting up the development environment, one of the first things you should try is actually deploying your plugin code to QGIS and seeing it in action. While other tools and methods exist, QGIS Plugin tools has a useful PluginMaker tool to help with this process. In OSGeo4W Shell, navigate to the directory containing the files plugin.py and build.py (by default myqgisplugin) and run the command python build.py deploy.

Restart QGIS, open the Plugins > Manage and Install Plugins menu, and select the Installed tab. A new plugin should be in the list of installed plugins:

Note: if you don’t see the plugin, ensure you are using the QGIS profile named “default”.

Note that in the future it’s a good idea to always create and use a separate profile for each plugin you develop. You can define the profile that the plugin is deployed to in build.py. See the QGIS plugin tools documentation for more information.

Tick the checkbox next to the plugin to enable it. Open the QGIS Python interpreter from Plugins > Python console. Now click the MyQGISPlugin button in the Plugins menu and you should see the following statement in the Python console panel:

You can now start making changes to the code inside the run method in plugin.py. Remember to always deploy your changes using build.py and restart QGIS or you won’t see any effect! Restarting QGIS after each change gets tedious very fast, so we recommend installing the Plugin reloader plugin from the official plugin repository to reload changes without needing to restart.

Make sure to check out the PyQGIS Developer Cookbook for lots of useful and practical examples how to use PyQGIS, and the QGIS Plugin Tools documentation for information on what other useful functions it provides and how they are used.

Need help?

Are you lost and feel like you need advice on how to proceed? Feel free to reach out to us at info@gispo.fi. We can help you take your plugin development skills to the next level with various PyQGIS-related courses with live instruction either on-premises or remotely. If you get in over your head, we can also develop customized plugins on your behalf or provide specialized consultation for your team on all QGIS plugin development related topics.

This article was initially published at www.gispo.fi by Mikael Vaaltola (Gispo Ltd.).