pyqgisdebug_ubuntu.md

Debugging QGIS 3.x python plugins on Ubuntu 24.04 using VS Code

My setup uses Ubuntu 22.04 running on Windows WSL2, which suppots executing GUI applications.

Setting up VS Code

NOTE: I'm using VS Code Python Debugger extension version v2024.12.0 (ms-python.debugpy), which uses debugpy.

QGIS

In my setup I'm running QGIS built from source, following the official instructions. My build is under /home/giohappy/dev/qgis/QGIS/build.

However this setup also works for QGIS installed normally (no source build).

Configure VS Code

I start VS Code from the plugin folder. In my case I'm testing QGISGeoNodePlugin that I have cloned from Github.

NOTE: The following is only required in case QGIS is built from source. In that case you need VS Code to be aware of the QGIS Python paths. For a standard QGIS setup the Python packages are already installed globally (apt).

settings.json

{
    "terminal.integrated.env.linux": {
        "PYTHONPATH": "/home/giohappy/dev/qgis/QGIS/build/output/python",
    },
    "python.analysis.include": [
        "/home/giohappy/dev/qgis/QGIS/build/output/python"
    ],
    "python.analysis.extraPaths": [
        "/home/giohappy/dev/qgis/QGIS/build/output/python"
    ]
}  

Launch.json

Remote debugger configuration for debugpy

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Remote Attach",
            "type": "debugpy",
            "request": "attach",
            "connect": {
                "port": 5678,
            }
        }
    ]
}

Build the plugin

From the plugin folder (e.g. /home/giohappy/dev/qgis/QGISGeoNodePlugin) run:

• `python -m venv venv && ./venv/bin/activate && pip install poetry
• pip install . to install the build deps
• python pluginadmin.py build

The plugin will be created under the build folder.

Then we symlink the plugin to the QGIS plugins folder:

• ln -s /home/giohappy/dev/qgis/QGISGeoNodePlugin/build/qgis_geonode/ /home/giohappy/.local/share/QGIS/QGIS3/profiles/default/python/plugins/qgis_geonode

Starting the debugpy server from QGIS

The QGIS DevTools QGIS Plugin needs debugpy. I have installed it globally with sudo apt install python3-debugy (pip install doesn't work for global installs in recent Ubuntu versions, because the Python environment is considered exteranlly managed).

Then:

• Run QGIS
• Enable the plugin from the Plugins Installer, if not yet enabled
• Start the debugpy server clicking the QGIS DevTools icon at the bottom right of QGIS
• If all goes fine the message bar should print "INFO Debug session started at 127.0.0.1:5678" inside the QGID DevTools log window

More information about the usage of QGIS DevTools can be found inside its documentation

Now you should be ready to debug!

Debugging

In VS Code

• start debugging using the Python: Remote Attach configuration defined above.
• Place the breakpoints inside the code inside the build folder.

Now you should be able to step debug in VS Code