QML Debugging in Visual Studio Code

We’re excited to announce a major step forward for QML development workflows with the upcoming 1.5.0 pre-release of Qt Qml Extension for Visual Studio Code. As part of this release, we’ve introduced initial support for QML debugging in VS Code – a feature that brings long-requested functionality closer to everyday usage for QML developers using lightweight and cross-platform tooling.

🔍 Supported Features

With this initial release of QML debugging support, you can now:

• Attach to a running QML application via TCP port — Quickly connect to remote or local QML apps without restarting, making testing and iteration faster.
  

• Inspect QML stack frames in the Call Stack view — Understand what your QML code is doing at each step and troubleshoot issues more effectively.
  

• View file/line-based source locations with proper stack trace navigation — Jump directly to the relevant part of your code, saving time when tracking down bugs.
  

• Step through code with — Gain full control over code execution to understand app behavior line by line:
  

  • Continue

  • Step Over

  • Step In

  • Step Out

🚀 Getting Started

1. Install Qt Extension for VS Code (Pre-release)

First, make sure you have the Qt Extension for VS Code installed and that you're using version 1.5.x or above of the Qt Qml Extension.

To install it:

1. Open the Extensions view in VS Code (Ctrl+Shift+X or ⇧⌘X).

2. Search for “Qt Qml” and select the extension published by The Qt Company.

3. Click the Switch to Pre-Release Version.

🧪 This enables access to the QML debugging features introduced in 1.5.0.

2. Add a Debug Configuration

To enable QML debugging, you need a debug configuration that connects to a running QML debug server.

🧭 Option A: Use the Add Configuration UI

1. Open the Run and Debug panel (Ctrl+Shift+D).

2. Click Add Configuration… at the bottom.

3. From the list, select Qt: QML: Attach by port:

   

This will generate the following config in your .vscode/launch.json file:

{
    "configurations": [
        {
            "name": "Qt: QML: Attach by port",
            "type": "qml",
            "request": "attach",
            "host": "localhost",
            "port": "Custom port or ${command:qt-qml.debugPort} for compound usage"
        }
    ]
}

🧭 Option B: Manually Add It

You can also manually paste the config above into your .vscode/launch.json.

Make sure the port and host match the ones you will use when launching your application.

3. Start the Debugger First

In VS Code:

1. Select the Attach to QML configuration.

2. Press F5 or click Start Debugging.

You’ll see a message like this, indicating the debugger is waiting:

4. Launch Your Application with Debugging Enabled

Now start your Qt application from the command line using the following argument:

<your-qt-app> -qmljsdebugger=host:127.0.0.1,port:12150,block,services:DebugMessages,QmlDebugger,V8Debugger,QmlInspector

• host:127.0.0.1 → Binds to localhost

• port:12150 → Must match launch.json

• block → Waits for the debugger before running

• services → Enables powerful debugging features:

  • DebugMessages

  • QmlDebugger

  • V8Debugger

  • QmlInspector

Once launched, the app will connect to the waiting debugger in VS Code and resume execution.

If you want to debug both QML and C++ code, you can take a look at our documentation here.

🔍 A Brief Overview of Supported Features

1. Inspect QML Stack Frames in the Call Stack View

When something goes wrong in a QML application, it’s important to understand the sequence of function calls that led to the issue. By exposing the QML call stack, this feature helps developers quickly locate the source of unexpected behavior, understand the context, and make more informed debugging decisions.

The QML debugger allows you to inspect QML stack frames directly in the Call Stack view. It provides a structured overview of active QML functions, enabling you to trace the execution flow and analyze how your application reached its current state.

2. View File/Line-Based Source Locations

Efficient debugging depends on quickly finding where an issue occurs in your code. This feature bridges the gap between runtime information and your source files, allowing you to move directly from a stack trace to the relevant file and line, which saves time and helps you stay in the flow.

With the debugger, you can view file and line-based source locations in the editor. Each stack frame includes precise location metadata, and clicking on a frame opens the corresponding file and line in the editor, allowing smooth and fast navigation through your code.

3. Step Through Code

Debugging is often about watching how the application behaves step-by-step. This feature gives you full control over the execution flow, allowing you to pause at any moment, investigate what’s happening, and proceed one step at a time to better understand or isolate the problem.

The debugger supports several stepping actions: Continue, Step Over, Step In, and Step Out. These commands let you resume execution, skip over functions, dive into them, or return to a previous context—all of which help in exploring the runtime behavior of your QML code with precision.

If you encounter any bugs or usability issues, please report them in our bug tracker.