Creating a QGIS plugin is much easier than it may seem, especially when you are new to programming. Thanks to Plugin Builder, you can generate the complete structure of a QGIS plugin in just a few minutes, without writing any complex code.
In this second article of the tutorial series, we will see how to create your first QGIS plugin using Plugin Builder, step by step: installing the tool, choosing the right template, disabling advanced options, and generating the plugin.
The goal is to quickly obtain a working plugin in QGIS, in order to understand the overall workflow before progressively diving into Python code.
Creating your first plugin with Plugin Builder
In the first article, we explained what QGIS plugins are used for and which files they are made of. Now it’s time to move on to practice.
The objective of this article is simple: create a functional QGIS plugin without writing complex code, in order to understand the basic development cycle of a plugin.
To do this, we will use an essential tool for beginners: Plugin Builder.
What is Plugin Builder?
Plugin Builder is an official QGIS plugin that automatically generates the skeleton of a QGIS plugin.
It creates for you:
- the folder structure,
- the essential Python files,
- the
metadata.txtfile, - a plugin that can be immediately loaded into QGIS.
Plugin Builder helps avoid common beginner mistakes and allows you to focus on what really matters: understanding and modifying an existing plugin.
Installing Plugin Builder
- Open QGIS
- Go to Plugins → Manage and Install Plugins
- Search for Plugin Builder
- Install it
Once installed, Plugin Builder is available from the Plugins menu.
Launching the creation wizard
- Go to Plugins → Plugin Builder → Plugin Builder
- The creation wizard opens
You will need to fill in several fields. Don’t worry: some of them are purely descriptive.
General plugin information
Plugin name and description
- Plugin name: a user-friendly name (e.g. MyFirstPlugin)
- Description: a short sentence explaining what the plugin does
These details will appear in the QGIS Plugin Manager.
Version and author
- Version: start simply with
0.1 - Author: your name or your organization’s name
Important technical settings
Choosing a template
Plugin Builder offers several templates.
For beginners, it is strongly recommended to choose:
Template: Tool button with dialog
This template is the most educational because:
- it creates a toolbar button in QGIS,
- it prepares a simple graphical dialog,
- it matches the structure of most common plugins.
It will serve as a solid foundation for the next articles.
Options to disable when starting
For a first plugin, it is recommended to disable all advanced options, especially:
- Internationalization (translations)
- Help (embedded documentation)
- Unit testing
- Advanced packaging
These features are useful for mature plugins, but they unnecessarily complicate the structure for beginners.
We will come back to them later, once the basics are well understood.
Plugin class
Plugin Builder asks for the name of the main plugin class.
Example:
- Plugin name:
MyFirstPlugin - Class:
MyFirstPlugin
By convention, using the same name and capitalization helps avoid confusion.
Menu and icon
You can specify:
- the menu where the plugin will appear (usually Plugins),
- an icon (optional at this stage).
These choices can easily be changed later.
Generating the plugin
Once all fields are filled:
- Click Generate
- Choose the destination folder
Plugin Builder automatically creates the plugin folder with all required files.
Where should the plugin be placed?
For QGIS to detect the plugin, it must be located in the user plugins directory.
Depending on your system:
- Windows
C:/Users/.../AppData/Roaming/QGIS/QGIS3/profiles/default/python/plugins - Linux
~/.local/share/QGIS/QGIS3/profiles/default/python/plugins - macOS
~/Library/Application Support/QGIS/QGIS3/profiles/default/python/plugins
💡 Tip: Plugin Builder usually suggests the correct folder by default.
Activating the plugin in QGIS
- Open Plugins → Manage and Install Plugins
- Go to the Installed tab
- Check your plugin
If everything went well, the plugin appears in the menu and can be activated.
👉 At this stage, the plugin does almost nothing… and that’s perfectly normal.
Understanding what Plugin Builder created
Before going any further, take some time to open the generated files:
__init__.pymetadata.txt- the main Python file
You should now recognize the elements described in the previous article.
Common beginner mistakes
- The plugin does not appear → wrong folder
- Error when loading → incorrect class name or capitalization
- QGIS refuses the plugin → incorrect minimum QGIS version
These errors are normal and part of the learning process.
What you have learned
By the end of this article, you now know how to:
- install Plugin Builder,
- generate an empty QGIS plugin,
- install it locally,
- activate it in QGIS.
You have crossed an important milestone: you are officially a QGIS plugin developer.
What’s next?
In the next article, we will see:
- how to add a button to QGIS,
- how to display a simple dialog window,
- how to structure the code without getting lost.
👉 A plugin that does nothing today can become a powerful tool tomorrow.
