# natvis4qt

**Repository Path**: GitHub-01Hub/natvis4qt

## Basic Information

- **Project Name**: natvis4qt
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-03
- **Last Updated**: 2026-03-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Nativs4Qt - Install natvis files for Qt

This repository contains:

- Up to date natvis files for Qt5 and Qt6
- Command line tool to install or update them in different locations

## Installation

`natvis4qt` is a simple command line tool to install or update the natvis files in different locations.

> [!CAUTION]
> The tool is in early stage, for now it can only overwrite natvis file in known locations. More later!

### Installation via [Scoop](https://scoop.sh/) (preferred)

```batch
scoop bucket add narnaud https://github.com/narnaud/scoop-bucket
scoop install natvis4qt
```

### Installation via [Cargo](https://doc.rust-lang.org/cargo/)

```
cargo install natvis4qt
```

### Or via archive files

1. Go to the [Releases](https://github.com/narnaud/natvis4qt/releases) page
2. Download the latest `natvis-x86_64-pc-windows-msvc.zip` file
3. Extract the files from it into a directory.

## Usage

Just run `natvis4qt install` on the command line and follow the instructions.

![Demo](assets/demo.gif)

The application is using different commands:

- `install`  Install the natvis files in known directories (MSVC and Qt)
- `update`   Update the natvis files
- `set`      Adjust natvis4qt's settings

## Integration

### Visual Studio

Select a version of `Visual Studio` when installing the natvis files.

This will install the natvis files in a central place that is used by Visual Studio. See documentation here: [Natvis file locations](https://learn.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects?view=vs-2022#BKMK_natvis_location)

Some visulaizers require debug symbols for Qt to be loaded. To load them, add the `bin` directory of your Qt installation (e.g. `C:\Qt\6.8.0\msvc2022_64\bin`) to the symbol search path under **Options > Debugging > Symbols**.

> [!CAUTION]
> The Qt VS Addin must be deactivated, as it is silently overwriting the natvis files in the Visualizers directory, see [QTVSADDINBUG-1308](https://bugreports.qt.io/browse/QTVSADDINBUG-1308).

#### Image Watch

It is possible to visualize `QImage` and `QPixmap` using the [Image Watch](https://learn.microsoft.com/en-us/previous-versions/visualstudio/visual-studio-2015/debugger/image-watch/image-watch) extension from Microsoft.

![Image Watch Example](assets/image-watch.png)

Install the extension, and click on the "View" button. It will open a new window with the image.

> [!WARNING]
>
> - it only supports image in RGB(A) with 32bits/pixel,
> - the Qt natvis file must to be in the default [Natvis file locations](https://learn.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects?view=vs-2022#BKMK_natvis_location).

### Visual Studio Code

#### Central Natvis file locations

Select `VS Code C/C++ Extension` when installing the natvis files.

This will install the natvis files in a central place that is used by Visual Studio. See available "documentation" here: [Natvis file locations](https://github.com/microsoft/vscode-cpptools/issues/925#issuecomment-591483777).

> [!WARNING]
> The files may disappear after an update of the [Microsoft C/C++ extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools).

#### Per-project vizualizer file

Another option is to install the natvis files int eh different Qt directories, and set a `visualizerFile` to your launch configuration. Edit your `launch.json` file (or the `launch` section of your `*.code-workspace` file) and add something like that:

```json
    "configurations": [
        {
            "name": "Current Target (VS)",
            "type": "cppvsdbg",
            "request": "launch",
            "program": "${command:cmake.launchTargetPath}",
            "visualizerFile": "${env:QTDIR}/natvis/qt6.natvis",
            "cwd": "${workspaceFolder}",
            "sourceFileMap": {
                "C:/work/build/qt5_workdir/w/s": "${env:QTDIR}/../Src",
                "Q:/qt5_workdir/w/s": "${env:QTDIR}/../Src",
                "C:/Users/qt/work/install": "${env:QTDIR}/../Src",
                "C:/Users/qt/work/qt": "${env:QTDIR}/../Src"
            },
            "symbolOptions": {
                "searchPaths": ["${env:QTDIR}/bin"],
            }
        }
    ]
```

> [!IMPORTANT]
>
> - The `QTDIR` environment variable must be set up before launching VS Code
> - You are limited to **only one** vizualizer file with `cppvsdbg`, see related [issue](https://github.com/microsoft/vscode-cpptools/issues/10917).

## Update

If you have installed `natvis4qt` using scoop, installed Natvis files will be automatically updated when updating via scoop.
If you don't want this mechanism, run:

```cmd
natvis4qt set --autoupdate false
```

To update them by hand, just run:

```cmd
natvis4qt update
```

## Natvis files

If you are only interested in natvis files, you can find them here:

- [qt5.natvis](https://github.com/narnaud/natvis4qt/blob/main/natvis/qt5.natvis)
- [qt6.natvis](https://github.com/narnaud/natvis4qt/blob/main/natvis/qt6.natvis)

You can find the current support of the Natvis file here: [SUPPORT.md](SUPPORT.md)

## License

The **natvis4qt** tool is licensed under the MIT license.

The natvis files are also licensed under the MIT license.

## Contributions

`qt5.natvis`:

- [The Qt Company](https://www.qt.io/)

`qt6.natvis`:

- [The Qt Company](https://www.qt.io/)
- [Klarälvdalens Datakonsult AB (KDAB)](https://www.kdab.com/)
- [@nerixyz](https://github.com/Nerixyz)
- [@nholthaus](https://github.com/nholthaus)
- [@aleksey-nikolaev](https://github.com/aleksey-nikolaev)