Skip to content
Tutorials Center
My learning

Topics

C++ Reference ยท Preprocessor, Tools and Concepts

The #include directive

Reference for the C++ #include directive: angle brackets versus quotes, search paths, include order, __has_include, and why includes are textual copy-paste.

#include is a preprocessor directive that replaces itself with the entire contents of another file. It runs before the compiler sees any C++ at all, so it is pure text substitution: after preprocessing, your source file and everything it includes form one long translation unit. Headers are how you share declarations (types, function prototypes, templates) between source files.

There are two forms. #include <name> searches the compiler's system include directories and is used for the standard library and installed third-party libraries. #include "name" searches the directory of the including file first, then falls back to the same places as the angle form, and is the usual choice for your own project headers.

C++
#include <vector>          // standard library header
#include "geometry.h"      // a header from your own project

Try it

C++ What an include really is

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

C++ Checking for a header with __has_include

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.

Syntax

C++
#include <header-name>
#include "source-file-name"
#include pp-tokens            // macro-expanded to one of the two forms above
#if __has_include(<header>) / __has_include("file")
Form Description
<name> Searches the implementation's system directories and any added with -I. For standard headers, an implementation may also treat the name as a built-in.
"name" Searches the including file's directory first (implementation-defined, but this is what GCC, Clang and MSVC do), then behaves like the angle form.
Macro form If neither form matches, the tokens are macro-expanded and must then produce one of the two forms. Rarely useful.
__has_include(x) Evaluates to 1 if the header can be included, else 0. Usable only in #if/#elif.

Errors: if the file cannot be found, compilation stops with a "No such file or directory" error. Including a file that is part of a cycle is bounded by the compiler's include depth limit, so always guard headers.

Usage notes

  • Order matters. A conventional order, from most to least specific: the header matching the .cpp file first (to prove it is self-contained), then your project headers, then third-party headers, then standard headers. Within a group, sort alphabetically.
  • Include what you use. Do not rely on one header including another; that is an accident of the implementation and breaks on the next compiler version. Include <cstdint> yourself when you use std::uint32_t.
  • Never #include a .cpp file to "share code"; it duplicates definitions and breaks the one-definition rule across files. Use a header and link the source file.
  • Headers hold declarations, plus things that must be visible at every use: templates, inline and constexpr functions, class definitions. Non-inline function and variable definitions in a header give "multiple definition" link errors.
  • Put no using namespace in headers. It leaks into every file that includes yours.
  • Use C++ names for C headers: <cstdio>, <cstring>, <cmath> put names in std:: (and usually in the global namespace too). Prefer the std:: spelling.
  • Compile times: every include is re-read for every translation unit. Forward-declare types when a pointer or reference is enough, and include the full header only in the .cpp file.
  • Modules (C++20) replace textual inclusion with import, and import <vector>; header units exist, but toolchain support is uneven; our runner does not support modules.
  • Where the compiler looks: add search directories with -Idir. -isystem dir marks them as system headers (warnings from them are hidden).
  • X-macros: an .def file included several times, each time after redefining a macro, is a legitimate textual trick for generating enum values and string tables.