Sign up for the KDAB Newsletter
Stay on top of the latest news, publications, events and more.
Go to Sign-up
Update 2025-03-12
The Qt6 natvis file have moved to the natvis4qt
repository. This repository contains:
qt5.natvis
, qt6.natvis
)natvis4qt
, a command line tool to install and update natvis files in known location It is highly recommended to use the natvis4qt
tool now. Please refer to the documentation for integration in Visual Studio or VS Code.
Not all Qt developers are using Qt Creator as their main IDE for development. Some of us are using other IDEs, like Visual Studio, Visual Studio Code or CLion, per choice or because a project requires it.
On Windows, with the MSVC compiler, the debugging experience with Qt 6 can be quite frustrating for some Qt types, like QMap
, QHash
or QVariant
. See, for example, the debug variable view for the same project running with Qt Creator (left) and Visual Studio Code (right):
I don't know about you, but for me the VS Code view is gibberish. It was way better with Qt 5, as seen below:
Let's see how to improve things...
The Natvis framework allows developers to write custom schemas to help visualize native objects. This is already used by the Qt VS Tools for Visual Studio, with Qt 5 and a Qt 6 specific files. You can download the official Qt natvis files here: Qt VS Tool github.
They are pre-processed and copied automatically by the plugin to %HOME%\Documents\Visual Studio 2022\Visualizers
. If you want to use them directly from github, make sure to remove all occurrences of ##NAMESPACE##::
.
If you look closely at the size of the file, you can see that the Qt 5 Natvis file is 40.9 KB. The Qt 6 Natvis file is only 18.5 KB, which is not 50% smaller than the Qt 5 -- au contraire! This means that a lot of types are not working anymore, most likely because the Qt 5 implementation didn't work during the migration to Qt 6 due to changes in the underlying data.
Let's see how far we can improve things here. This blog won't be about the how (it involved a lot of cursing...), but only about the improvements made to the qt6.natvis file.
For developers in a hurry, you can download the updated Natvis file here:
https://github.com/narnaud/natvis4qt/releases/latest/download/qt6.natvis
QMap
ImprovementsQMap
was already working, but I wanted a nicer view, with [key]: value display.
QHash
ImprovementsQHash
was the very reason I started the journey; I just wanted to see something, ideally, like QMap
.
Unfortunately, it's not supported on CLion, which is missing support for the CustomListItems
Natvis tag.
QMultiHash
ImprovementsOnce QHash
was done, QMultiHash
was quite easy. Please note that the view is slightly different from the std::unordered_map
equivalent; the Qt version is showing a list of values for one key, while the std version shows a list of (key, value) pairs with duplicated keys.
Like QHash
, QMultiHash
view is not supported in CLion.
QVariant
ImprovementsAfter looking at the containers, I decided to look at QVariant
. Unfortunately, not all types are properly handled, but at least the static primitives, core templates, and most of the core classes are. If the type is unknown, it will show at least the typeId
, so the developer can know what is inside the QVariant
.
The full list is available here: Qt6 Natvis support
Follow the instructions here to add a natvis file to your project: Add a .natvis file to a C++ project.
We already discussed it in another blog post: VS Code for Qt Applications – Part 2. Just a quick recap:
launch.json
file (that's the "Debug: Add Configuration..." command)visualizerFile
property to the qt6.natvis fileThis is an example launch.json
file that works well with CMake project:
{
"version": "0.2.0",
"configurations": [
{
"name": "qt6.4.2-msvc",
"type": "cppvsdbg",
"request": "launch",
"program": "${command:cmake.launchTargetPath}",
"visualizerFile": "${workspaceFolder}/qt6.natvis",
"sourceFileMap": {
"C:/work/build/qt5_workdir/w/s": "C:/Qt/6.4.2/Src",
"Q:/qt5_workdir/w/s": "C:/Qt/6.4.2/Src",
"C:/Users/qt/work/install": "C:/Qt/6.4.2/Src",
"C:/Users/qt/work/qt": "C:/Qt/6.4.2/Src"
}
}
]
}
That's a good question, and my first attempt at trying to fix this issue was to look at Qt Creator. After all, it's using the same compiler and debugger. Surely, I can find something I can use. Quoting the documentation:
Qt Creator extends the command line debugger by loading the qtcreatorcdbext.dll extension library into it. The library must be available in the libs\qtcreatorcdbext64 and libs\qtcreatorcdbext32 folder. To install it there, select Qt Creator CDB Debugger Support when you install Qt Creator.
Again, quoting the documentation:
Qt Creator uses Python scripts to translate raw memory contents and type information data from native debugger backends (GDB, LLDB, and CDB are currently supported) into the form presented to the user in the Locals and Expressions views.
That's the reason why the debugger is slower in Qt Creator (you can disable it from the Debugger->CDB preference page, with the "Use Python dumper" option). Unfortunately, it's not usable for Visual Studio and VS Code.
It's unfortunately impossible to go as far as what Qt Creator can do, but the changes to the qt6.natvis file improve the debugging experience quite a lot already, and we are close to feature parity with qt5.natvis. The file is part of our KDToolBox project. KDToolBox is a collection of useful code, scripts and snippets you are free to use; you can download it here:
https://github.com/narnaud/natvis4qt/releases/latest/download/qt6.natvis
This file can be used for Visual Studio, VS Code, and CLion IDEs, with the exception of QHash
and QMutiHash
not working with CLion. If something is missing, send me a note, no promises though.
About KDAB
The KDAB Group is a globally recognized provider for software consulting, development and training, specializing in embedded devices and complex cross-platform desktop applications. In addition to being leading experts in Qt, C++ and 3D technologies for over two decades, KDAB provides deep expertise across the stack, including Linux, Rust and modern UI frameworks. With 100+ employees from 20 countries and offices in Sweden, Germany, USA, France and UK, we serve clients around the world.
Stay on top of the latest news, publications, events and more.
Go to Sign-up
Upgrade your applications from Qt 5 to Qt 6 with KDAB’s migration services. Get a free migration assessment and join a hands-on workshop to prepare your team for a successful transition!
Learn more
4 Comments
9 - Mar - 2023
Serhiy
Let's be honest, debugging in QtCreator for Windows is a real pain.
31 - Mar - 2023
Michal Lazo
Nice. Thank you. Any chance to mainline this?
31 - Mar - 2023
Nicolas Arnaud-Cormos
The goal is indeed to push it upstream, I didn't have time yet. Please note that upstream you have
##NAMESPACE##::
, while the version here doesn't (so it can be usable as is, while the upstream version is pre-processed by the plugin).24 - Jul - 2024
Reshma Dhotre