INCLUDE-WHAT-YOU-USE(1)

💖 INCLUDE-WHAT-YOU-USE(1) 💖

okay bestie, gather round, because this is the manual page for include-what-you-use, aka the little tool that goes through your C and C++ source files and analyzes your #includes. it's giving "your header hygiene coach" and honestly? we're obsessed. 🦋

---

✨ NAME ✨

include-what-you-use — analyze #includes in C and C++ source files 💅

---

🌸 DESCRIPTION 🌸

here's the vibe, the whole usage situation, keep it in your notes:

USAGE: include-what-you-use [-Xiwyu --iwyu_opt]... <clang opts> <source file>

so basically you pass IWYU-specific options through with -Xiwyu, and here are the <iwyu_opts> you can specify (like, for example, -Xiwyu --verbose=3). no cap, this is the full list 👇

• --check_also=<glob> — tells iwyu to print iwyu-violation info for all files matching the given glob pattern, on top of the default behaviour (which is reporting for the input .cc file and its associated .h files). 🫶 you can pass this flag multiple times if you want to specify multiple glob patterns, she's flexible like that.
• --keep=<glob> — tells iwyu to always keep these includes. 💖 and yes, this flag can also be specified multiple times to specify multiple glob patterns.
• --mapping_file=<filename> — gives iwyu a mapping file. that's it, that's the whole thing 🎀
• --no_default_mappings — do not add iwyu's default mappings. bye default mappings 👋
• --pch_in_code — mark the first include in a translation unit as a precompiled header. use --pch_in_code to prevent IWYU from removing necessary PCH includes, okay? 😭 though Clang forces PCHs to be listed as prefix headers, the PCH-in-code pattern can be used with GCC and is standard practice on MSVC (e.g. stdafx.h). iconic messy cross-compiler lore fr fr.
• --prefix_header_includes=<value> — tells iwyu what to do with in-source includes and forward declarations involving prefix headers. so a prefix header is a file included via the command-line option -include. and if that prefix header makes an include or forward declaration obsolete, the presence of such an include can be controlled with the following values:
  • add: new lines are added ✨
  • keep: new lines aren't added, existing are kept intact 🫶
  • remove: new lines aren't added, existing are removed 💀
  • default value is add. periodt.
• --transitive_includes_only — do not suggest that a file add foo.h unless foo.h is already visible in the file's transitive includes. no sneaky invisible headers bestie 🙈
• --max_line_length — maximum line length for includes. note that this only affects comments and alignment thereof — the maximum line length can still be exceeded with long file names (default: 80). she's trying her best, okay?? 😭
• --comment_style=<level> — set verbosity of 'why' comments to one of the following values:
  • none: do not add 'why' comments
  • short: 'why' comments do not include namespaces
  • long: 'why' comments include namespaces
  • default value is short. 💅
• --no_comments — do not add 'why' comments. silent mode, mysterious queen 🎀
• --update_comments — update and insert 'why' comments, even if no #include lines need to be added or removed. glow-up your comments for no reason at all, we support it 💖
• --no_fwd_decls — do not use forward declarations. we're going the long way, apparently 🚶♀️
• --verbose=<level> — the higher the level, the more output. the more she talks, the more you learn iykyk 🔥
• --quoted_includes_first — when sorting includes, place quoted ones first. quoted girls to the front 💅✨
• --cxx17ns — suggests the more concise syntax introduced in C++17. modern, forward-thinking, lowkey stunning 🌈
• --error[=N] — exit with N (default: 1) for iwyu violations. she's MAD now 😤
• --error_always[=N] — always exit with N (default: 1) (for use with make -k). consistent drama, every single time 💀
• --debug=flag[,flag...] — debug flags (undocumented). spooky. mysterious. no notes 🙈
• --regex=<dialect> — use specified regex dialect in IWYU:
  • llvm: fast and simple (default) ⚡
  • ecmascript: slower, but more feature-complete ✨
• --experimental=flag[,flag...] — enable experimental features:
  • clang_mappings: use Clang canonical standard library mappings instead of built-in mappings 🧚

and in addition to IWYU-specific options, you can specify the following options without the -Xiwyu prefix 🫶:

• --help — prints this help and exits. she's helpful and she leaves, queen behaviour 👑
• --version — prints version and exits. 💜

⚠️ real talk though: all those --iwyu_opts need to be sent through with -Xiwyu (except the last two, --help and --version, which go in bare), so don't be out here typing them raw and then acting surprised when clang yells at you. 😭

---

and that's the whole page bestie, thanks for reading my manual page essay 🎀 this was include-what-you-use version 8.23-1build1, dated January 2026, written under the User Commands section of the manual — mwah, go fix your includes, ily 💖✨🦋