#metabuild #natvis #debug


A metabuild/build.rs compatible crate to embed .natvis debug visualizer files into your executable's .pdbs, for ease of debugging

4 stable releases

1.0.3 Sep 7, 2022
1.0.2 Dec 30, 2019
1.0.1 Nov 30, 2019
0.0.1 Nov 28, 2019

#170 in Debugging

33 downloads per month


80 lines


GitHub Build status Crates.io unsafe: no rust: 1.39.0+ Open issues License dependency status

A metabuild / build.rs compatible crate to embed .natvis debug visualizer files into your executable's .pdbs, for ease of debugging.


  • Natvis and PDBs being Microsoft technologies, this won't have any effect unless using MSVC-based build toolchains.
  • While crate-type=rlib crates can contain .natvis files, they should not directly rely on natvis-pdbs. (Due to the way crates are isolated for build, natvis-pdbs will only work when used for the final .exe, .lib, or .dll crate at this time.)
  • This abuses the %LINK% environment variable since there's currently no stable build.rs-friendly arbitrary link-args.

Quick Start

To author crates containing .natvis files (example)

Place one or more natvis files inside any of:

  • the root folder of your crate.
  • inside the {root}\src folder.
  • inside a {root}\debug_metadata folder.

Any other locations (including subdirectories of the above) will not (currently) be searched. See Recommended Reading bellow for more information about the .natvis format.

<?xml version="1.0" encoding="utf-8"?>
<AutoVisualizer xmlns="http://schemas.microsoft.com/vstudio/debugger/natvis/2010">
  <Type Name="example_crate_with_natvis::Flags">
        <Item Name="bits"   ExcludeView="sparse">bits,bb</Item>
        <Item Name="A (1)"  ExcludeView="sparse">(bits &amp; (1 &lt;&lt; 0)) != 0</Item>
        <Item Name="B (2)"  ExcludeView="sparse">(bits &amp; (1 &lt;&lt; 1)) != 0</Item>
        <Item Name="C (4)"  ExcludeView="sparse">(bits &amp; (1 &lt;&lt; 2)) != 0</Item>

To consume .natvis files via build.rs (example)

Add the following to your executable's Cargo.toml:

natvis-pdbs = "1"

And the following to your build.rs:

fn main() {

To consume .natvis files via metabuild (nightly only, example)

Add the following to your executable's Cargo.toml:

cargo-features = ["metabuild"]

metabuild = ["natvis-pdbs"]

natvis-pdbs = "1"


Licensed under either of

at your option.


Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.


~33K SLoC