g++ -E: show the preprocessed C++ source (debug macros and #include)

g++ -E file.cpp runs only the preprocessor and writes the result to standard output: every #include is replaced by the header's text, macros are expanded, #if blocks that are false are removed, and comments disappear. Nothing is compiled. It is the tool for understanding why a macro misbehaves, which header defines something, or which branch of an #ifdef was taken. Add -P to drop the line markers and -o file.ii to save the output.

Macro expansion made visible

The example uses Clang 20 from the Zig 0.15.1 toolchain (installed from PyPI with uv); cxx below is that compiler, and g++ accepts the same options:

cxx() { uv run -q --no-project --python 3.13 --with ziglang==0.15.1 python -m ziglang c++ -fno-color-diagnostics "$@"; }
cat > macros.cpp <<'EOF'
#define SQUARE(x) x * x
#define SQUARE_OK(x) ((x) * (x))
#define NAME "errcodex"
#ifdef FAST
int mode = 1;   // fast path
#else
int mode = 0;   // default path
#endif
int a = SQUARE(1 + 2);
int b = SQUARE_OK(1 + 2);
const char* n = NAME;
EOF
echo "== g++ -E -P"
cxx -E -P macros.cpp
echo "== g++ -E -P -DFAST"
cxx -E -P -DFAST macros.cpp | grep mode
echo "== line markers without -P"
cxx -E macros.cpp | grep -m1 '^# 1 "macros.cpp"'
echo "== <iostream> expands to"
printf '#include <iostream>\n' > io.cpp
lines=$(cxx -std=c++17 -E -P io.cpp | wc -l)
[ "$lines" -gt 10000 ] && echo "more than 10000 lines"

== g++ -E -P
int mode = 0;
int a = 1 + 2 * 1 + 2;
int b = ((1 + 2) * (1 + 2));
const char* n = "errcodex";
== g++ -E -P -DFAST
int mode = 1;
== line markers without -P
# 1 "macros.cpp"
== <iostream> expands to
more than 10000 lines

SQUARE(1 + 2) expands to 1 + 2 * 1 + 2, which is 5, not 9: the classic missing-parentheses bug, plainly visible in the -E output. The #ifdef branch changes with -DFAST, comments are gone, and a single #include <iostream> becomes tens of thousands of lines.

Useful combinations

When -E helps

• "was not declared" after a macro: if a name disappears or turns into something else, a macro with the same name is the usual cause. Look at the expanded line; see was not declared in this scope.
• Which header provides a declaration: g++ -E -H lists the include tree, and the line markers in -E output show the file where a declaration came from. Missing standard headers often cause no member named X in namespace std.
• Platform #ifdefs: check which branch is active for a given target or -D set without building.
• Bug reports: compiler developers ask for a preprocessed file (-E, or -save-temps), because it reproduces the problem without your include paths.

Pitfalls

• The output depends on every flag that affects the preprocessor: -std, -D, -I, the target. Use the same flags as the real build, or the result can differ.
• -E does not check that the code is valid C++; syntax errors appear only when compiling.
• The __cplusplus value changes with -std (for example 201703L for C++17), which switches code paths in headers; see -std=c++17.

FAQ