C++ #include: Angle Brackets vs Double Quotes

C++ uses #include to copy the contents of a header file into a source file before compilation. The main difference is the header-search order: quoted includes generally look near the current file first, while angle-bracket includes search configured system or library include directories. In practice, use quotes for headers owned by your project and angle brackets for standard-library, system, and installed third-party library headers.

The #include directive is handled by the C++ preprocessor, before the compiler processes C++ code.

#include "MyFile.h"
#include <vector>

Both directives request a header file. The delimiters communicate where the build tool should look for it.

• #include "file.h" generally searches the directory containing the including file first, then other configured include directories.
• #include <file.h> generally searches configured include directories intended for system, standard-library, or external-library headers.

The precise search rules are affected by the compiler and build configuration, so they are not identical on every platform. However, the convention is stable and useful:

• Use quotes for headers that are part of the current application or repository.
• Use angle brackets for the C++ standard library, operating-system headers, and installed dependencies.

For example, QPushButton belongs to the Qt framework. Once Qt's include directories are configured in the build system, this is conventional:

#include <QPushButton>

A header such as MyFile.h that lives in your own source tree is conventionally included with quotes:

Think of header lookup as finding a book.

• Double quotes mean: check my desk first, then check the library. Your desk is the directory of the file currently doing the include.
• Angle brackets mean: go directly to the library catalog. The catalog contains locations configured by the compiler and build system.

Your own project files are usually on your desk, so use quotes. Standard and installed library files belong in the library catalog, so use angle brackets.

The basic forms are:

#include "relative-or-project-header.h"
#include <library-or-system-header>

Project header

Suppose these files are in the same directory:

src/
├── main.cpp
└── Greeter.h

Greeter.h:

#pragma once

#include <string>

std::string makeGreeting(const std::string& name);

main.cpp:

#include "Greeter.h"

#include <iostream>

int main() {
    std::cout << makeGreeting("Ava") << '\n';
}

indicates that is a header supplied by this project. The standard headers and use angle brackets because the C++ implementation supplies them.

Consider this project layout:

project/
├── include/
│   └── app/
│       └── Config.h
└── src/
    └── main.cpp

main.cpp contains:

#include "app/Config.h"
#include <iostream>

int main() {
    std::cout << "Started\n";
}

Assume the build configuration adds project/include as an include directory.

1. The preprocessor reads #include "app/Config.h".
2. It first generally tries the directory containing main.cpp, such as project/src/app/Config.h.
3. That file does not exist, so it checks configured include directories.
4. It finds project/include/app/Config.h and inserts that header's contents into main.cpp.
5. Next, the preprocessor reads #include <iostream>.
6. It searches the compiler's configured standard-library include locations and finds iostream.

• C++ standard library: Use angle brackets for headers such as <vector>, <string>, <memory>, and <iostream>.
• Platform APIs: System-provided headers, such as Windows headers or POSIX headers, are commonly included with angle brackets.
• Third-party libraries: Use angle brackets for installed dependencies such as Qt, Boost, fmt, or SDL when their include paths are configured by the build system.
• Application modules: Use quotes for headers written and maintained in your repository, such as "UserService.h" or "app/Config.h".
• Generated project headers: Generated headers that are output into a project build directory are often included with quotes, because they are part of the project's build output.

The important point is not where a file happens to be located on one computer. It is whether the header is owned by your project or provided as an external dependency.

In a real codebase, include style is usually defined by a project style guide.

A common ordering pattern is:

#include "app/Window.h"       // Current project
#include "app/Settings.h"     // Current project

#include <QPushButton>          // Third-party dependency
#include <fmt/format.h>         // Third-party dependency

#include <memory>               // C++ standard library
#include <string>               // C++ standard library

Many teams also separate headers into groups with blank lines, often placing the matching project header first in a .cpp file:

#include "UserService.h"

#include "Database.h"
#include "Validator.h"

#include <string>

Assuming angle brackets mean “only system headers”

Angle brackets are also commonly used for third-party libraries:

#include <QPushButton>
#include <fmt/format.h>

They mean the header should be found through configured include paths rather than being treated as a nearby project file.

Using a local file with the same name as a standard header

Suppose your project has a file named vector or vector.h. This can create confusing lookup behavior, especially if quoted includes are used carelessly.

Prefer the real standard header:

#include <vector>

Also avoid naming your own headers after standard-library headers.

Using quotes for every header

This may compile, but it hides the distinction between project and external dependencies:

// Works in some configurations, but is not the usual style.
#include "vector"
#include "QPushButton"

Use the conventional delimiter to communicate ownership clearly.

Quotes vs relative paths

#include "app/Config.h"       // Preferred when `include/` is configured
#include "../../include/app/Config.h" // Fragile; depends on directory layout

A project-relative include path plus build-system configuration is easier to maintain.

vs

// Current project header
#include "MyFile.h"
#include "app/Config.h"

// C++ standard library header
#include <vector>
#include <string>

// Installed third-party library header
#include <QPushButton>
#include <fmt/format.h>

• Use quotes for headers owned by your project.
• Use angle brackets for standard, system, and external-library headers.
• Quoted headers generally search the including file's directory first.
• Angle-bracket headers generally search configured library and system paths.
• Exact lookup details depend on the compiler and build configuration.
• Include every header needed directly by the file; do not depend on accidental transitive includes.
• Prefer stable project paths such as "app/Config.h" over "../../app/Config.h".

Does #include "file.h" always search the current directory first?

It generally does, but exact search behavior is implementation- and build-tool-dependent. Treat it as the normal convention, not a guarantee independent of compiler settings.

Can I include my own header with angle brackets?

Yes, if its directory is configured as an include path. Some projects do this intentionally. However, quotes are the more common convention for headers owned by the current project.

Can I include <vector> with quotes?

A compiler may find it in some configurations, but use <vector>. It clearly identifies a C++ standard-library dependency and avoids lookup surprises.

Why does #include <QPushButton> not include a .h extension?

Qt chooses header names such as QPushButton. Header file naming is determined by the library; C++ does not require a .h extension.

What happens if the header cannot be found?

Preprocessing stops with an error such as file not found or No such file or directory. Check the spelling, path, and build-system include directories.

Do quotes and angle brackets change runtime behavior?

No. They affect how the preprocessor locates a header before compilation. They do not create a runtime file lookup.

Should every file include its own dependencies?

• C++ preprocessor directives — #include is processed before normal C++ compilation.
• Header files and source files — Understanding declarations, definitions, and file organization explains why headers are included.
• Include guards and #pragma once — These prevent a header from being processed more than once in a translation unit.
• Translation units — An included header becomes part of the source text compiled as one unit.
• Build systems and include paths — Tools such as CMake configure where compilers find project and dependency headers.
• Include what you use — Directly including required dependencies prevents fragile builds.
• C++ modules — Modules are a modern alternative to many traditional header-based dependencies.