QGIS for Devs

Setting up a QGIS workspace

IDE

The Visual Studio Code IDE is a free and lightweight editor with advanced debugging tools, including extensions tailored for Python and QGIS development. It also supports version control and code formatting, making plugin development more efficient.

PyCharm is a Python-focused alternative that is easier to configure than VSCode. The Community Edition is free. It includes a powerful built-in debugger.

QGIS Extensions

There is the Plugin Reloader plugin to easily apply your code changes without restarting QGIS. This greatly speeds up debugging and iteration, making development smoother.

plugin development cycle

1. Modify the Python files of the AIAMAS plugin.
2. Save changes in VSCode or PyCharm.
3. Use the Plugin Reloader to apply changes instantly.

Manual installation of a python plugin

If a Python plugin is not available in the official repository, it can be manually installed as follows:

1. Clone the repository or create a new plugin in any directory.
2. QGIS stores plugins by default in the python/plugins folder within the user-specific QGIS profile directory. On Windows, the full path is typically: C:\Users\Username\AppData\Roaming\QGIS\QGIS3\profiles\default\python\plugins
Replace Username with your actual Windows username.
3. The AppData\Roaming folder is hidden by default. To access it: * Enable "Show hidden files" in Windows Explorer. * Alternatively, type %appdata% in the Explorer search bar, navigate back one level to AppData.
All the QGIS plugins are stored inside the default/python/plugins folder.
4. Create a shortcut to the cloned or created plugin in this directory, but only include the code folder. Not the entire repository. Files likeREADME.md should not be included in this shortcut.

After restarting QGIS, the plugin will now appear under Extensions > Manage and Install Plugins > Installed.

Writing plugins

Documentation for Writing PyQGIS Plugins

Python:

• Writing a QGIS Plugin in Python
• Getting started with a QGIS Plugin
• Structuring Python Plugins
• PyQGIS Developer Cookbook

C++:

• QGIS Plugins with C++ Manual

Other:

• QGIS API
• API Overview/Poster by Thomas Gratier

• QGIS Manual - Guide > QGIS Coding and Compilation Guide
• Forum
• Wiki-Artikel
• Community Support

Using the QGIS Python Console

To open the Python console in QGIS:

1. Navigate to Menu > Plugins
2. Use the shortcut Ctrl+Alt+P

Expected Console Output:

Python Console
Use iface to access QGIS API interface or Type help(iface) for more info.
_

Avoiding Crashes with QgsGeometry

If using:

geom = iface.activeLayer().selectedFeatures()[0].geometry()

QGIS may crash due to a long-standing unresolved issue 777 with Python bindings.

Instead, use:

 feat = iface.activeLayer().selectedFeatures()[0]
 geom = QgsGeometry(feat.geometry())

Testing: geom.type(), geom.length(), geom.asPolyline() crashes if the line has three vertices, with only two vertices it returns an empty array.

See also e.g. Python Scripting (PyQGIS).

Debugging QGIS-Plugins

Debugging Methods

Developers can debug their QGIS plugin using different methods:

• print() for basic console output

• qgsMessageLog.logMessage() to log messages inside QGIS

• icecream (ic()) for advanced debugging with variable inspection

We recommend using IceCream (ic()) over print() for debugging. It displays variables and expressions with their values, formats data structures, and highlights output. Typing is faster, and it can optionally show the filename, line number, and function context.

Remote Debugging with PyCharm(Debug Server)

If running QGIS externally, enable remote debugging:

1. Install the PyCharm Debugger:

   	pip install pydevd-pycharm
   	

2. Add the following to the plugin code:

   	import pydevd_pycharm
   	pydevd_pycharm.settrace('localhost', port=5678, stdoutToServer=True, stderrToServer=True, suspend=False)
   	

3. In PyCharm, go to Run > Edit Configurations > Python Remote Debug
4. Set Host: localhost, Port: 5678, then click Start Debugging

Testing Plugins

• Writing Uni Tests for QGIS Plugins: http://snorf.net/blog/2014/01/04/writing-unit-tests-for-qgis-python-plugins/
• Configuration for Debugging and Unit Testing of PyQGIS: See QGIS Plugins mit Python.
• Testen von Qt-GUI Komponenten: http://www.voom.net/pyqt-qtest-example

Using PyCharm simplifies QGIS plugin development with testing features

Publication of a Plugin

Releasing your plugin

A metadata.txt file is essential as it contains descriptive information about the plugin. This helps users and QGIS manage and understand plugin details effectively.

Requirements

• If hasProcessingProvider exists, it should be mentioned in the "about" section.
• Processing tools should be described in description, about, and added as a tag.
• The licence must be GPL 2 or 3. Does the LICENSE file exist in the repo? If not, add GPL 3 from the template.
• The homepage must point to the actual website or at least the repo’s README.md (not just the repo itself).

More details about a metadata.txt.

Pre-Upload Checklist

• Ensure all attributes in metadata.txt are correct.

• Increment the plugin version before uploading.

• Change experimental flag if needed (set to false to appear in the default QGIS Plugin list).

• Set an icon (no strict size limit specified).

• Remove unnecessary files (*.pyc, .gitignore, IDE-specific files, etc.).

• Use only ASCII characters in filenames (Umlauts will cause errors).

• Plugin directory names cannot contain hyphens.

• ZIP the plugin directory before upload.

Uploading

In order to upload a plugin on the official QGIS page a OSGeo ID (user) is required (e.g. user account "geometalab").

1. The user account can be created here under sign-in: https://www.osgeo.org/
2. On the page login with your OSGeo ID.
3. The plugin (ZIP archive) can be uploaded here. Check experimental field if the plugin still is experimental.
4. After uploading the plugin it won't be immediately available in the plugin list. It first has to get approved. The approval can take up to 2 weeks. Check How to add your plugin to this repository for the criteria the plugin has to meet in order to get approved.

Weblinks

• QGIS Homepage (Project-Team QGIS)
• QGIS Wiki
• QGIS Blog