Debug Qt for Python applications

You can debug Python applications that contain both Python and QML code with debugpy and the QML debugger.

Debug Python code

To debug only the Qt for Python code in an application, follow the instructions in VS Code: Python debugging in VS Code.

To launch and debug Qt for Python applications:

1. Open a launch.json file. For more information, see Debug Qt applications.
2. Select Python Debugger.
3. Select Add Configuration, and then select the Qt: PySide: Launch debug configuration.

The configuration looks as follows:

"configurations": [
    Pyside
    {
        "name": "Python Debugger: Current File",
        "type": "debugpy",
        "request": "launch",
        "program": "${file}",
        "console": "integratedTerminal"
    },
    {
        "name": "Qt: PySide: Launch",
        "type": "debugpy",
        "request": "launch",
        "program": "${workspaceFolder}/main.py",
        "preLaunchTask": "PySide: build"
    }
]

Debug mixed Python and QML code

You can create a debug configuration that first starts an application and then attaches both debugpy and the QML debugger to it using a port number that the Qt: Acquire Port pre-launch task acquires.

Turn on QML debugging

To turn on QML debugging, add the following code to your QML application:

from pathlib import Path
from argparse import ArgumentParser

from PySide6.QtGui import QGuiApplication
from PySide6.QtQml import QQmlApplicationEngine, QQmlDebuggingEnabler

if __name__ == "__main__":
    argument_parser = ArgumentParser()
    argument_parser.add_argument("-qmljsdebugger", action="store",
                                 help="Enable QML debugging")
    options = argument_parser.parse_args()
    if options.qmljsdebugger:
        QQmlDebuggingEnabler.enableDebugging(True)

    app = QApplication(sys.argv)
    engine = QQmlApplicationEngine()

Launch and debug applications

The QML debugger connects to a socket server that is run by the QmlEngine instance. Specify the port number in the launch configuration.

To debug a Qt Quick application that contains both Python and QML code:

1. Open a launch.json file. For more information, see Debug Qt applications.
2. Select Python Debugger.
3. Select Add Configuration, and then select the Qt: PySide: Launch with QML Debugger debug configuration.
4. In args, set the value of "port" to the port number to use:

   "configurations": [
       {
       "name": "Qt: PySide: Launch with QML debugger",
       "type": "debugpy",
       "request": "launch",
       "program": "${workspaceFolder}/main.py",
       "preLaunchTask": "PySide: build",
       "args": [
           "-qmljsdebugger=port:<port_number>,block,services:DebugMessages,QmlDebugger,V8Debugger"
   ]

5. Select Add Configuration, and then select the Qt: QML: Attach by port debug configuration.
6. Set the port number as the value of the port option in the launch.json file:

   "configurations": [
       {
           "name": "Qt: QML: Attach by port",
           "type": "qml",
           "request": "attach",
           "host": "localhost",
           "port": "<port_number>"
       },

7. Add a compound launch task for Python/QML debugging to the launch.json file:

   "compounds": [
       {
           "name": "Python/QML",
           "configurations": [
               "Qt: PySide: Launch with QML debugger,
               "Qt: QML: Attach by port"
           ]
       }
   ]

8. Run the compound debug configuration.

Automatically assign port numbers

Use the ${command:qt-qml.debugPort} variable and a compound launch and pre-launch task to automatically assign port numbers:

"configurations": [
    {
        "name": "Qt: PySide: Launch with QML debugger",
        "type": "debugpy",
        "request": "launch",
        "program": "${workspaceFolder}/main.py",
        "preLaunchTask": "PySide: build",
        "args": [
            "-qmljsdebugger=port:${command:qt-qml.debugPort},block,services:DebugMessages,QmlDebugger,V8Debugger"
            ]
    },
    {
        "name": "Qt: QML: Attach by port",
        "type": "qml",
        "request": "attach",
        "host": "localhost",
        "port": "${command:qt-qml.debugPort}"
    },
],
"compounds": [
    {
        "name": "Python/QML",
        "configurations": [
            "Qt: PySide: Launch with QML debugger,
            "Qt: QML: Attach by port"
        ],
        "preLaunchTask": "Qt: Acquire Port",
    }
]