9.25. QGIS DevTools — debugging QGIS plugins

9.25.1. Preface

Developing QGIS plugins is a powerful way to extend the functionality of one of the world’s leading open-source GIS platforms. But despite the flexibility of Python and QGIS’s API, one thing has long been missing from the developer experience: an efficient, modern debugging workflow.

For many plugin developers, the standard method of debugging involves printing to the console or using workarounds to attach debuggers manually. This process is slow and often frustrating, especially when dealing with complex logic or UI interactions.

That’s why we built a tool to bridge the gap. QGIS DevTools is a QGIS plugin that enables smooth integration with Visual Studio Code, one of the most widely used and feature-rich development environments. With this plugin, developers can set breakpoints, inspect variables, and step through code directly from Visual Studio Code. Thanks to its modular architecture, the plugin can be extended to support other IDEs like PyCharm or Eclipse in the future, as well as additional development scenarios beyond debugging.

In this article, we’ll introduce the plugin and show how it can streamline and modernize your QGIS plugin development workflow.

9.25.2. Setting up QGIS

9.25.2.1. Installing dependencies

DevTools uses debugpy as the underlying library, so you need to install it first. If you are Windows user, we recommend to use OSGeo4W installation of QGIS for plugin development.

You can add debugpy installation to your build in Libs category.

../../_images/add_debugpy.png

If you are a Linux user, you can install python3-debugpy using your OS package manager. For example:

apt get install python3-debugpy

9.25.2.2. Installing QGIS DevTools

After that you could install QGIS DevTools from standard plugins repository (Plugins — Manage and install plugins — All — QGIS DevTools)

../../_images/devtools_install.png

Installed plugin management is available via small bug icon installed_icon in the right bottom part of the QGIS interface.

../../_images/interface_icon.png

Plugin settings are also available in menu Plugins — QGIS DevTools.

9.25.2.3. QGIS DevTools settings

In settings you could select debug adapter (currently supports only debugpy for Visual Studio Code and Visual Studio, more to come), set if you want to enable debugger on QGIS startup and show notification on debugger start.

Enabling the debugger leads to activating the local server app. In the Adapter settings block you could set up hostname and port(s) for this server. Selecting range instead of single value for Port would allow you to run several QGIS instances with active debuggers simultaneously.

../../_images/Adapter_settings.png

9.25.3. Setting up VS Code

9.25.3.1. Installing Python debugger extension

Python debugger extension for VS Code is needed. Go to Extensions tab (Ctrl+Shift+X), search for Python debugger and install it. Then restart VS Code.

../../_images/python_debugger_extension.png

9.25.3.2. Opening plugin code and setting up debugger

For example we will debug the OSMInfo QGIS plugin, which could be installed from the standard plugins repository. You could try the same path, or use your own plugin.

To copy the plugin’s location, it is convenient to simply right click on the Installed version number in the plugins manager and press the Copy link button.

Open the whole plugin directory in VS Code using File — Open Folder and paste copied path, then open folder.

Next step is to create an empty .vscode/launch.json file in plugins directory root.

../../_images/launch_json_file.png

Return back to QGIS and press the Start button in the DevTools panel.

../../_images/start_button.png

After that you will see the standard QGIS blue notification about started session, with Copy launch.json template button.

../../_images/start_notification.png

Press it, and paste copied template to .vscode/launch.json file created before.

In pasted code, in configurations/pathMappings/remoteRoot element replace <YOUR_PLUGIN_NAME> text to plugin’s directory name, in example case osminfo.

../../_images/replace_dir_name.png

After that switch to the Run & Debug tab (Ctrl + Shift + D) and run Attach to QGIS.

../../_images/attach_to_qgis.png

Debug session is active now. On VS Code side you should see a panel with debugging commands:

../../_images/debug_panel.png

On QGIS side you should see, that DevTools icon changed it’s color to green, and status changed to “client connected”.

../../_images/stop_button.png

We are ready for debugging now.

9.25.4. Debugging process

All VS Code debug workflows are now available, you could find detailed information here: https://code.visualstudio.com/docs/python/debugging

Let’s try some simple things. Open osminfotool.py file, find row 97 and add breakpoint to it by pushing the red circle left to row number.

../../_images/breakpoint_attempt.png

We asked the debugger to stop when reaching this row of code. In the plugin’s code this place is about actions after clicking on map. Switch to QGIS, select OSMInfo tool and click to any location on the map. Interface freezes — it is correct behaviour, the debugger stopped the process.

In VS Code you can see that the breakpoint was reached. In the variables panel you could explore all currently available variables used in the plugin. You could also use all these variables in Debug console, for example ask for mouse click coordinate with

e.pos().x()
../../_images/console_variables.png

After that, using debug panel debug_panel_2 you could move to the next code row or next breakpoint. These tools make the process of understanding what happens in the plugin much easier. Happy debugging!

9.25.5. Conclusion

We hope that QGIS DevTools will make the lives of plugin developers easier. Based on community requests, we plan to expand the list of supported IDEs and development support mechanisms in general. Feel free to share your thoughts and feedback!