Skip to content
A tool for use with clang to analyze #includes in C and C++ source files
C++ Python C Other
Branch: master
Clone or download
kimgr Improve resugaring of function template argument types
Clang commit 3ced23976aa8a86a17017c87821c873b4ca80bc2 removed sugar from
ImplicitCastExprs in certain situations.

The sugar still seems to be available from the DeclRefExpr used for
function arguments, so use a RAV to find the first ImplicitCastExpr or
DeclRefExpr that provides a sugared type.

This loses one diagnostic in I haven't been able to form a
story around why it disappears, but it doesn't look critically useful,
so I removed it.
Latest commit a40a287 Jan 7, 2020
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs [docs] Fix misnumbered reference Dec 4, 2019
more_tests Remove Google-specific handling of third-party Mar 10, 2019
tests Improve resugaring of function template argument types Jan 7, 2020
.clang-format Update .clang-format not to sort using declarations Dec 27, 2019
.gitignore Add subdirectory 'build' to .gitignore Oct 6, 2019
.markdownlint.json Add custom markdownlint config and update docs to be markdownlint clean May 29, 2018
.travis.yml [travis] Work around missing libBye.a upstream Jan 6, 2020
CMakeLists.txt Add man page as a brief reference documentation Nov 3, 2019 Fix copy-paste mistake Oct 19, 2019
LICENSE.TXT Clean up third-party license listing Nov 11, 2015 [docs] Remove half-truth that Clang 9 maps to IWYU master Oct 19, 2019
boost-1.64-all-private.imp Add boost import reference files for version 1.64 May 26, 2018
boost-1.64-all.imp Change "folders" to "directories" in Boost mappings. Jul 17, 2019
boost-all-private.imp Collect Boost and Qt mappings created by Scott Howard aka @maqifrnswa. Sep 10, 2015
boost-all.imp Change "folders" to "directories" in Boost mappings. Jul 17, 2019
clang-6.intrinsics.imp imp files for Intel intrinsics May 29, 2018 Ignore file extension case when detecting main CU Dec 2, 2019 Ignore file extension case when detecting main CU Dec 2, 2019
gcc-8.intrinsics.imp imp files for Intel intrinsics May 29, 2018
gcc.libc.imp Add more libc mapping(s). Feb 2, 2016
gcc.stl.headers.imp Update mappings Nov 4, 2018
gcc.symbols.imp Add mappings for POSIX time types Feb 23, 2019 [python] Clean up license headers Dec 4, 2019
include-what-you-use.1 Add man page as a brief reference documentation Nov 3, 2019 Add script to check license headers Dec 4, 2019 Remove dead return Dec 27, 2019
iwyu.gcc.imp Remove Google-specific handling of third-party Mar 10, 2019 Improve resugaring of function template argument types Jan 7, 2020
iwyu_ast_util.h Rename port.h -> iwyu_port.h Dec 26, 2019 Handle precomputed template arguments in libc++ like in libstdc++ (is… Sep 7, 2014
iwyu_cache.h Rename port.h -> iwyu_port.h Dec 26, 2019 Clang r370122: ArrayRef in CompilerInvocation::CreateFromArgs Sep 1, 2019
iwyu_driver.h Make header guards consistent May 25, 2016
iwyu_getopt.h Rename port.h -> iwyu_port.h Dec 26, 2019
iwyu_globals.h Add command line option --keep=<glob> Mar 30, 2019 Rename port.h -> iwyu_port.h Dec 26, 2019
iwyu_include_picker.h Fix symbol mappings to relative includes Sep 1, 2019
iwyu_lexer_utils.h Simplify handling of defined() operator Jan 19, 2019 Update for Clang r341573 Sep 12, 2018
iwyu_location_util.h Update to reflect changes in Clang. Oct 11, 2016
iwyu_output.h Expose use flags directly from OneUse Dec 26, 2019 Remove ".." from normalized file paths Jul 17, 2019
iwyu_path_util.h Remove Google-specific handling of third-party Mar 10, 2019
iwyu_port.h Fix up license header for iwyu_port.h Dec 27, 2019 Rename port.h -> iwyu_port.h Dec 26, 2019
iwyu_preprocessor.h Rename port.h -> iwyu_port.h Dec 26, 2019
iwyu_stl_util.h Fix #310: Replace Each with C++11 range for loops Jul 11, 2016
iwyu_string_util.h Rename port.h -> iwyu_port.h Dec 26, 2019 [python] Clean up license headers Dec 4, 2019 [iwyu_tool] Fail fast if include-what-you-use is not found Dec 21, 2019 [python] Clean up license headers Dec 4, 2019
iwyu_use_flags.h Introduce an extra use flag UF_ExplicitInstantiation Dec 7, 2018 Fixed file heading comments not matching the filename (issue #83). Pa… Nov 25, 2012
iwyu_verrs.h Handle internal headers guarded by macro and x-macros (fix issue #109). Aug 15, 2016
iwyu_version.h Bump master version to 0.14 Oct 26, 2019
libcxx.imp <bits/move.h> is a part of <utility>. Mar 9, 2018
qt4.imp Collect Boost and Qt mappings created by Scott Howard aka @maqifrnswa. Sep 10, 2015
qt5_11.imp Add new qt5.11 mapping file Jul 10, 2019
qt5_4.imp Correct Qt mapping file to take in account both include formats (syst… Jul 10, 2019 Add skipped associated headers to IWYU analysis Dec 21, 2019 [python] Clean up license headers Dec 4, 2019
stl.c.headers.imp Specify public STL headers explicitly (issue #132). Sep 28, 2014

Include What You Use

Build Status

For more in-depth documentation, see docs.

Instructions for Users

"Include what you use" means this: for every symbol (type, function, variable, or macro) that you use in (or foo.cpp), either or foo.h should include a .h file that exports the declaration of that symbol. (Similarly, for, either or foo.h should do the including.) Obviously symbols defined in itself are excluded from this requirement.

This puts us in a state where every file includes the headers it needs to declare the symbols that it uses. When every file includes what it uses, then it is possible to edit any file and remove unused headers, without fear of accidentally breaking the upwards dependencies of that file. It also becomes easy to automatically track and update dependencies in the source code.


This is alpha quality software -- at best (as of July 2018). It was originally written to work specifically in the Google source tree, and may make assumptions, or have gaps, that are immediately and embarrassingly evident in other types of code.

While we work to get IWYU quality up, we will be stinting new features, and will prioritize reported bugs along with the many existing, known bugs. The best chance of getting a problem fixed is to submit a patch that fixes it (along with a test case that verifies the fix)!

How to Build

Include-what-you-use makes heavy use of Clang internals, and will occasionally break when Clang is updated. Usually such discrepancies are detected by build bot and fixed promptly.

The IWYU master branch follows Clang trunk.

We also have convenience tags and branches for released versions of Clang (called clang_<version>, e.g. clang_5.0). To build against a Clang release, check out the corresponding branch in IWYU before configuring the build. More details in the instructions below.

We assume you already have compiled LLVM and Clang libraries on your system, either via packages for your platform or built from source. You can use this mapping table to combine Clang and IWYU versions correctly:

Clang IWYU version IWYU branch
3.6 0.4 clang_3.6
3.7 0.5 clang_3.7
3.8 0.6 clang_3.8
3.9 0.7 clang_3.9
4.0 0.8 clang_4.0-r2
5.0 0.9 clang_5.0
6 0.10 clang_6.0
7 0.11 clang_7.0
8 0.12 clang_8.0
... ... ...

NOTE: If you use the Debian/Ubuntu packaging available from, you'll need the following packages installed:

  • llvm-<version>-dev
  • libclang-<version>-dev
  • clang-<version>

Packaging for other platforms will likely be subtly different.

To set up an environment for building:

  • Create a directory for IWYU development, e.g. iwyu

  • Clone the IWYU Git repo:

    iwyu$ git clone
  • Presumably, you'll be building IWYU with a released version of LLVM and Clang, so check out the corresponding branch. For example, if you have Clang 6.0 installed, use the clang_6.0 branch. IWYU master tracks LLVM & Clang trunk:

    iwyu$ cd include-what-you-use
    iwyu/include-what-you-use$ git checkout clang_6.0
  • Create a build root and use CMake to generate a build system linked with LLVM/Clang prebuilts:

    # This example uses the Makefile generator, but anything should work.
    iwyu/include-what-you-use$ cd ..
    iwyu$ mkdir build && cd build
    # For IWYU 0.10/Clang 6 and earlier
    iwyu/build$ cmake -G "Unix Makefiles" -DIWYU_LLVM_ROOT_PATH=/usr/lib/llvm-6.0 ../include-what-you-use
    # For IWYU 0.11/Clang 7 and later
    iwyu/build$ cmake -G "Unix Makefiles" -DCMAKE_PREFIX_PATH=/usr/lib/llvm-7 ../include-what-you-use

    (substitute the llvm-6.0 or llvm-7 suffixes with the actual version compatible with your IWYU branch)

    or, if you have a local LLVM and Clang build tree, you can specify that as CMAKE_PREFIX_PATH for IWYU 0.11 and later:

    iwyu/build$ cmake -G "Unix Makefiles" -DCMAKE_PREFIX_PATH=/llvm-trunk/build ../include-what-you-use
  • Once CMake has generated a build system, you can invoke it directly from build, e.g.

    iwyu/build$ make

Instructions for building Clang are available at

How to Install

If you're building IWYU out-of-tree or installing pre-built binaries, you need to make sure it can find Clang built-in headers (stdarg.h and friends.)

Clang's default policy is to look in path/to/clang-executable/../lib/clang/<clang ver>/include. So if Clang 3.5.0 is installed in /usr/bin, it will search for built-ins in /usr/lib/clang/3.5.0/include.

Clang tools have the same policy by default, so in order for IWYU to analyze any non-trivial code, it needs to find Clang's built-ins in path/to/iwyu/../lib/clang/3.5.0/include where 3.5.0 is a stand-in for the version of Clang your IWYU was built against.

Note that some distributions/packages may have different defaults, you can use clang -print-resource-dir to find the base path of the built-in headers on your system.

So for IWYU to function correctly, you need to copy the Clang include directory to the expected location before running (similarly, use include-what-you-use -print-resource-dir to learn exactly where IWYU wants the headers).

This weirdness is tracked in issue 100, hopefully we can make this more transparent over time.

How to Run

The original design was built for Make, but a number of alternative run modes have come up over the years.

Plugging into Make

The easiest way to run IWYU over your codebase is to run

  make -k CXX=/path/to/llvm/Debug+Asserts/bin/include-what-you-use


  make -k CXX=/path/to/llvm/Release/bin/include-what-you-use

(include-what-you-use always exits with an error code, so the build system knows it didn't build a .o file. Hence the need for -k.)

Include-what-you-use only analyzes .cc (or .cpp) files built by make, along with their corresponding .h files. If your project has a .h file with no corresponding .cc file, IWYU will ignore it unless you use the --check_also switch to add it for analysis together with a .cc file.

Using with CMake

CMake has grown native support for IWYU as of version 3.3. See their documentation for CMake-side details.

The CMAKE_CXX_INCLUDE_WHAT_YOU_USE option enables a mode where CMake first compiles a source file, and then runs IWYU on it.

Use it like this:

  mkdir build && cd build
  CC="clang" CXX="clang++" cmake -DCMAKE_CXX_INCLUDE_WHAT_YOU_USE="path/to/iwyu;-Xiwyu;any;-Xiwyu;iwyu;-Xiwyu;args" ...

or, on Windows systems:

  mkdir build && cd build
  cmake -DCMAKE_CXX_COMPILER="%VCINSTALLDIR%/bin/cl.exe" -DCMAKE_CXX_INCLUDE_WHAT_YOU_USE="path/to/iwyu;-Xiwyu;any;-Xiwyu;iwyu;-Xiwyu;args" -G Ninja ...

The option appears to be separately supported for both C and C++, so use CMAKE_C_INCLUDE_WHAT_YOU_USE for C code.

Note that with Microsoft's Visual C++ compiler, IWYU needs the --driver-mode=cl argument to understand the MSVC options from CMake.

Using with a compilation database

The script predates the native CMake support, and works off the compilation database format. For example, CMake generates such a database named compile_commands.json with the CMAKE_EXPORT_COMPILE_COMMANDS option enabled.

The script's command-line syntax is designed to mimic Clang's LibTooling, but they are otherwise unrelated. It can be used like this:

  mkdir build && cd build
  CC="clang" CXX="clang++" cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ... -p .

or, on Windows systems:

  mkdir build && cd build
  python -p .

Unless a source filename is provided, all files in the project will be analyzed.

See --help for more options.

Applying fixes

We also include a tool that automatically fixes up your source files based on the IWYU recommendations. This is also alpha-quality software! Here's how to use it (requires python):

  make -k CXX=/path/to/llvm/Debug+Asserts/bin/include-what-you-use 2> /tmp/iwyu.out
  python < /tmp/iwyu.out

If you don't like the way munges your #include lines, you can control its behavior via flags. --help will give a full list, but these are some common ones:

  • -b: Put blank lines between system and Google includes
  • --nocomments: Don't add the 'why' comments next to includes

How to Correct IWYU Mistakes

  • If has removed an #include you actually need, add it back in with the comment '// IWYU pragma: keep' at the end of the #include line. Note that the comment is case-sensitive.
  • If has added an #include you don't need, just take it out. We hope to come up with a more permanent way of fixing later.
  • If has wrongly added or removed a forward-declare, just fix it up manually.
  • If has suggested a private header file (such as <bits/stl_vector.h>) instead of the proper public header file (<vector>), you can fix this by inserting a specially crafted comment near top of the private file (assuming you can write to it): '// IWYU pragma: private, include "the/public/file.h"'.

Current IWYU pragmas are described in IWYUPragmas.

You can’t perform that action at this time.