QGIS Plugin Builder

.. image:: https://github.com/jonah-sullivan/Qgis-Plugin-Builder/actions/workflows/tests.yml/badge.svg :target: https://github.com/jonah-sullivan/Qgis-Plugin-Builder/actions :alt: Tests

.. image:: https://img.shields.io/codecov/c/github/jonah-sullivan/Qgis-Plugin-Builder/QGIS4 :target: https://codecov.io/gh/jonah-sullivan/Qgis-Plugin-Builder?branch=QGIS4 :alt: Test Coverage

.. image:: https://img.shields.io/github/last-commit/jonah-sullivan/Qgis-Plugin-Builder :target: https://github.com/jonah-sullivan/Qgis-Plugin-Builder/commits :alt: Last commit

.. image:: https://img.shields.io/github/stars/jonah-sullivan/Qgis-Plugin-Builder?style=social :target: https://github.com/jonah-sullivan/Qgis-Plugin-Builder/stargazers :alt: GitHub stars

.. image:: https://img.shields.io/github/issues/jonah-sullivan/Qgis-Plugin-Builder :target: https://github.com/jonah-sullivan/Qgis-Plugin-Builder/issues :alt: Open issues

.. image:: https://img.shields.io/badge/License-GPL_v2-blue.svg :target: https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html :alt: License: GPL v2

.. image:: https://img.shields.io/badge/QGIS-Plugin_Repository-brightgreen :target: https://plugins.qgis.org/plugins/pluginbuilder4/ :alt: QGIS Plugin Repository

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg :target: https://github.com/psf/black :alt: Code style: black

.. image:: https://img.shields.io/badge/imports-isort-ef8336.svg :target: https://pycqa.github.io/isort/ :alt: Imports: isort

.. image:: https://img.shields.io/badge/linting-flake8-yellowgreen.svg :target: https://flake8.pycqa.org/ :alt: Linting: flake8

.. image:: https://img.shields.io/badge/Python-3.x-blue?logo=python :target: https://www.python.org/ :alt: Python

.. image:: https://img.shields.io/badge/QGIS-Plugin-green?logo=qgis :target: https://qgis.org/ :alt: QGIS Plugin

QGIS Plugin Builder is a Python-based tool that helps developers quickly scaffold fully structured QGIS plugins. It generates clean boilerplate code, reusable templates, and a best-practice project layout—so you can focus on building geospatial functionality instead of setup. Whether you're new to QGIS plugin development or an experienced GIS developer, this tool streamlines the process of creating plugins with a consistent architecture, reducing development time and improving maintainability.

Key Features

• Fast plugin scaffolding with minimal setup
• Pre-built boilerplate following QGIS best practices
• Template-driven structure for easy customization
• Built for Python and the QGIS API
• Ideal for GIS developers, teams, and plugin prototyping

.. figure:: help/source/images/wizard_required_info.png

Walkthrough

1. Install Plugin Builder

Open QGIS and go to Plugins → Manage and Install Plugins. Search for Plugin Builder and install it.

2. Open Plugin Builder

Go to Plugins → Plugin Builder → Plugin Builder. The wizard opens.

3. Fill in the required fields

On the first page enter:

• Class name — CamelCase Python class name (e.g. MyPlugin)
• Module name — snake_case file name (e.g. my_plugin)
• Plugin name — human-readable title shown in QGIS menus
• Description — one-line summary of what the plugin does
• Version — starting version number (e.g. 0.1)
• Minimum QGIS version — minimum compatible version (required; defaults to 4.0)
• Maximum QGIS version — maximum compatible version (required; defaults to 4.99)
• Author and Email

On the second page enter a longer About description.

4. Choose a template

On the template page select one of:

• Tool button with dialog — toolbar button that opens a modal dialog
• Tool button with dock widget — toolbar button that opens a dock panel
• Processing provider — adds an algorithm to the Processing toolbox

5. Set publication info (optional)

Enter URLs for your bug tracker, home page, and repository. Add tags to help users find the plugin on the QGIS Plugin Repository.

6. Choose additional components

Check the components you want included:

• Internationalization — stub i18n setup for adding translated strings
• Help — a Sphinx documentation project in help/
• Unit tests — a pytest test suite wired to pytest-qgis
• Helper scripts — scripts for publishing to plugins.qgis.org and managing translations
• Makefile — a GNU Makefile for building and deploying
• pb_tool — a pb_tool.cfg for the pb_tool command-line deploy tool

7. Generate the plugin

Click Generate, choose an output directory, and click Generate again. Plugin Builder writes all the files into a new directory named after your module.

Resource file compilation is optional. It is best practice to reference resources such as icons and images using os.path rather than Qt's resource system::

icon_path = os.path.join(os.path.dirname(__file__), 'icon.png')
icon = QIcon(icon_path)

This avoids the need to run rcc at build time and keeps your assets visible as ordinary files. If you do use a .qrc file, compile it with::

rcc -g python resources.qrc -o resources.py

8. Deploy and test

Use pb_tool to deploy the generated plugin to your QGIS plugin directory::

cd my_plugin
pip install pb_tool
pb_tool deploy

Then open QGIS, enable the plugin in Plugins → Manage and Install Plugins, and run it to confirm it loads correctly.

9. Start developing

The generated plugin is a working stub. Open the source files in your editor, implement your logic, and use pb_tool deploy -q to redeploy quickly as you iterate.

Documentation

See the help_ documentation for full details on each wizard field and deployment option.

.. _help: https://jonah-sullivan.github.io/Qgis-Plugin-Builder/

Contributing

New plugin templates can be added by creating a subdirectory below plugin_templates and registering the template in plugin_templates/__init__.py