Developing a QGIS Plugin: Why and How to Create Your Own Plugin

[EN]Developing a QGIS Plugin: Why and How to Create a Plugin

20 May 202618 May 2026 Atilio Francois No Comments

Developing a QGIS plugin may seem reserved for experienced programmers, but with the right approach, anyone can create their own. This tutorial explains why plugins are essential, what they can do, and how a plugin is structured, including the role of each file, making it accessible even for beginners.

In this tutorial, we will explore what QGIS plugins are for, why they are so useful in everyday workflows, and especially how a QGIS plugin is structured: which files it contains and what their roles are.

This series of articles is aimed at QGIS users who are beginners in Python, teachers, local government staff, and anyone who wants to automate their workflows or create tools tailored to their professional needs.

Contenu

Introduction

QGIS is today one of the most widely used open-source GIS platforms in the world. Its functional richness is impressive, but what really makes it powerful is its extensibility through plugins.

A QGIS plugin allows you to add custom features: automate repetitive tasks, create tools adapted to a specific profession, test new methods, or simply make daily work easier.

This tutorial is intentionally aimed at people with limited programming experience. It does not aim to make you a Python expert but to give you the foundations to:

understand how a QGIS plugin works,
modify an existing plugin,
create your own simple and useful tools.

The goal is to learn just enough Python and QGIS architecture to become autonomous.

Why Develop Your Own QGIS Plugins?

Automate Repetitive Tasks

If you use QGIS often, you have probably repeated the same steps several times:

loading layers,
applying styles,
running a series of processes,
exporting results.

A plugin can group these actions under a single button.

Adapt QGIS to Your Workflow

The needs of a GIS professional, teacher, government agent, or researcher are not always covered by standard tools. A plugin can integrate:

business rules,
consistency checks,
specific calculations.

Learn Programming Gradually

Developing a QGIS plugin is an excellent way to get started with Python:

the results are concrete and visual,
errors are often easy to identify,
progress can be made in small, manageable steps.

Share (or Keep for Yourself)

A plugin can remain strictly personal, be shared within a team, or be published publicly through the official QGIS repository.

What Does a QGIS Plugin Consist Of?

A QGIS plugin is primarily a folder containing several files, each with a specific role. The good news: you do not need to understand everything in depth right away.

Here’s the minimal structure of a plugin:

MyPlugin/
├── __init__.py
├── metadata.txt
├── my_plugin.py
└── resources.qrc (optional)

We will go through these files one by one.

The `init.py` File

This is the entry point of the plugin.

Its main role is to tell QGIS which Python class should be loaded when the plugin is activated.

Simplified example:

def classFactory(iface):
    from .my_plugin import MyPlugin
    return MyPlugin(iface)

At this stage, remember that:

this file is mandatory,
it links QGIS to your main code.

Line-by-Line Explanation

1️⃣ def classFactory(iface):

✔ QGIS requires a function with this exact name: classFactory.

When QGIS loads your plugin, it automatically calls:

classFactory(iface)

and passes:

iface = the QGIS interface object (QgisInterface)

This object gives access to:

the map canvas,
the Plugins menu,
the toolbar,
the active layer,
messages/logs,
etc.

➡️ This is the central object that allows a plugin to interact with QGIS.

2️⃣ from .my_plugin import MyPlugin

The dot (.) means: “from the same folder as this file”.

QGIS loads the main class from:

my_plugin.py

This class contains:

initGui() → adds actions, menus, icons
unload() → removes plugin elements
business functions (tool activation, window display, etc.)

➡️ This is the root class of the plugin, controlling everything.

3️⃣ return MyPlugin(iface)

QGIS expects an instance of the class, not the class itself.

So we:

instantiate MyPlugin,
pass it the QGIS interface (iface).

QGIS will then:

call initGui() when activating the plugin,
call unload() when deactivating.

➡️ This is the concrete creation of the plugin in QGIS.

Summary

__init__.py tells QGIS which class to use for the plugin.
The classFactory() function is mandatory.
iface provides full access to the QGIS interface.
The plugin starts functioning only after instantiating:

MyPlugin(iface)

The `metadata.txt` File

This file is fundamental: without it, QGIS will not recognize the plugin.

It contains general information:

plugin name,
description,
author,
version,
minimum QGIS version.

Example:

[general]
name=My First Plugin
description=A simple plugin to learn
version=0.1
author=Your Name
qgisMinimumVersion=3.16

This file is what appears in the QGIS Plugin Manager.

The Main Python File (e.g., `my_plugin.py`)

This is where the core of the plugin resides.

It typically contains:

the main plugin class,
the initGui() and unload() methods,
the code that adds a button or menu in QGIS.

Simplified example:

class MyPlugin:
    def __init__(self, iface):
        self.iface = iface

    def initGui(self):
        pass

    def unload(self):
        pass

Don’t worry if this seems confusing—each element will be explained in detail in future articles.

Optional but Common Files

Graphical Interfaces (`.ui`)

QGIS uses Qt for GUIs. .ui files are created with Qt Designer, without coding.

They allow you to build windows with:

buttons,
dropdown lists,
input fields.

Resources (`resources.qrc`)

This file collects:

icons,
images,
other graphical resources.

It is compiled into Python so it can be used in the plugin.

What You Need to Remember for Now

At this stage, the key points are:

a QGIS plugin is a file structure, not a big complex program,
each file has a specific role,
you can create simple, useful plugins with very little code.

What’s Next?

In the next article, we will see:

how to create an empty plugin using Plugin Builder,
where to place the files,
how to load and test the plugin in QGIS.

The goal will be to have a first functional plugin, even if it doesn’t do much yet.

👉 The most important thing is not to go fast, but to understand each step.

Si cet article vous a intéressé et que vous pensez qu'il pourrait bénéficier à d'autres personnes, n'hésitez pas à le partager sur vos réseaux sociaux en utilisant les boutons ci-dessous. Votre partage est apprécié !