skip to content

Modules and Import

C++20 modules export declarations from a compiled interface instead of textual inclusion, and C++23 adds import std. Interviewers ask what modules fix and why adoption is slow.

on this pageshow

explore

questions

4

In C++23, after import std; why does code using assert or INT_MAX still need an #include, and what does std.compat add?

level: middleimportance: should knowfreq 35%

answer

  1. declarations travel, macros do not
  2. assert, INT_MAX, errno are macros
  3. C headers are not importable
  4. std.compat adds the global names
  5. include before import on Clang

basics

~20 s

import std exports declarations only; assert, INT_MAX, errno, EOF and offsetof are macros, so they still need #include <cassert> or <climits>. std.compat additionally exports the C library names in the global namespace, such as ::printf.

solid answer

~40 s

C++23's `import std;` imports a named module that exports the declarations of the importable C++ library headers and of the C++ headers for C library facilities, all in namespace `std`. Importing a named module never makes macros visible, and many C-heritage facilities are specified as macros: `assert`, `INT_MAX`, `errno`, `EOF`, `stdout`, `offsetof`. Those still need `#include <cassert>`, `<climits>` and friends, and the `<c...>` headers are not in the standard's list of importable headers, so `import <cassert>;` is not a portable substitute. Often the better fix is a declaration instead of a macro: `std::numeric_limits<int>::max()` comes through `import std;`. `import std.compat;` exports everything `std` does plus the global-namespace C names such as `::printf` and `::size_t`.

go deeper

for a junior

Remember that import std; gives the standard library's declarations, while assert and INT_MAX are macros and still need their #include.

for a middle

Explain why macros cannot cross a named module boundary, which common names are macros, and what std.compat adds over std.

for a senior

Handle the mixed state of real code: include-before-import ordering on Clang, the C headers not being importable, and the feature-test macro guarding the module path.

for a principal

Decide when a codebase can rely on import std given its compilers and build tooling, and how to keep a header fallback for toolchains that lack it.

## What `import std;` is C++23 standardised two **standard library modules**: - **`std`** – exports the declarations in namespace `std` provided by the importable C++ library headers (`<vector>`, `<string>`, `<format>` and the rest of that table) and by the C++ headers for C library facilities (`<cstdio>`, `<cmath>`, `<cstdint>` and so on). It also exports the global `operator new` and `operator delete`. - **`std.compat`** – exports everything `std` does and additionally the matching declarations in the **global namespace** for the C library facilities, so `::printf`, `::size_t` and `::strlen` work as they do after a C-style `#include <stdio.h>`. The feature-test macro is `__cpp_lib_modules`, set to `202207L` in both the C++23 and C++26 drafts. Implementations ship the module as source (libc++ ships `.cppm` files) that the build compiles into a BMI for the current compiler and flags; the module itself is portable, its compiled form is not. ## Why macros do not come along A macro is a preprocessor entity: it exists in translation phase 4, before declarations exist. A named module is a translation unit that has been compiled past that point, so the standard says plainly that importing a named module does not make macros visible – only importing a **header unit** (`import <vector>;`, `import "config.h";`) does. The library clause repeats it for the standard modules, naming `assert`, `errno`, `offsetof` and `va_arg` as examples. Several facilities that look like functions or constants are specified as macros in the library synopses: | Name | Specified in | What to use instead, if anything | |---|---|---| | `assert` | `<cassert>` | keep `#include <cassert>` | | `INT_MAX`, `UINT_MAX` | `<climits>` | `std::numeric_limits<int>::max()` | | `errno` | `<cerrno>` | keep `#include <cerrno>`, or `std::error_code` APIs | | `EOF`, `stdout` | `<cstdio>` | `#include <cstdio>`; `std::print` writes to stdout without naming it | | `offsetof` | `<cstddef>` | keep `#include <cstddef>` | So after `import std;` alone, `assert(x > 0);` is an undeclared identifier and `INT_MAX` is unknown, while `std::numeric_limits<int>::max()` and `std::printf` work. A C++23 file that needs both looks like this (not compiled here: the toolchain used for checking ships no standard library module source): ```cpp #include <cassert> // macros: still included, and before the import #include <climits> import std; // C++23: declarations only int main() { int budget = std::numeric_limits<int>::max(); // a declaration: fine via import std assert(budget == INT_MAX); // both macros come from the #includes std::println("budget {}", budget); } ``` ## Why `import <cassert>;` is not the fix The standard calls the headers in its main C++ library header table **importable C++ library headers**, and only those are guaranteed to be importable as header units. The `<c...>` headers for C library facilities are in a separate table and are not on that list, so `import <cassert>;` may or may not work depending on the implementation. The portable fix is the plain `#include`. ## Mixing `#include` and `import std;` The standard requires that a library declaration denotes the same entity whichever way it was made reachable, so a file may both include `<cassert>` and import `std`. Implementations still have rough edges: 1. Clang documents that including a header **after** importing a module that provides the same declarations is not well supported and may be rejected, while include-then-import is accepted; libc++'s module notes repeat the advice to include headers first. 2. Put the `#include` lines in the global module fragment when the file is itself a module unit, and before the imports in an ordinary source file. 3. Keep the macro-only headers small and few; most code needs only `<cassert>` and perhaps `<cerrno>`. ## What `std.compat` is for Code ported from C, or written in the habit of calling `printf` unqualified, would need `std::printf` everywhere after `import std;`. `import std.compat;` exports the global-namespace spellings too, so that code compiles unchanged. It still does not supply any macro: `EOF` and `stdout` need `<cstdio>` either way. ## Availability `import std;` is a C++23 feature, and as an extension libc++ also offers it in C++20 mode. Toolchain support is newer than the standard: libc++ marks its module support experimental, and the module source must be compiled into a BMI by the build before the first import. On the Apple clang 21 used for this answer no standard library module source was installed, so the behaviour above is stated from the C++23 draft and the libc++ documentation rather than from a run.

  • How can a library tell at compile time whether import std is available?
    Test the feature-test macro `__cpp_lib_modules`, which the C++23 and C++26 drafts define as `202207L` in `<version>`. Because it is a macro it must come from `#include <version>` (or a header unit), not from `import std;`. In practice the build system also has to know, since it must compile the standard library module's source into a BMI before any file imports it.
  • Does import std; give you std::size_t but not ::size_t?
    Yes. The `std` module exports the C library declarations only inside namespace `std`, so `std::size_t` and `std::printf` work but the unqualified global spellings are not guaranteed. `import std.compat;` exports the global-namespace versions as well, which is what code written against `<stdio.h>` habits expects.

  • import std brings in every standard macro, including assert.
  • You can always write import <cassert>; instead of including it.
  • std.compat is the C++20 version of the std module.
  • import std replaces the need for any #include in a C++23 file.
  • A prebuilt std BMI can be shared between different compilers.

Assumes C++23, which added the std and std.compat modules (__cpp_lib_modules 202207L); the macro rule comes from C++20's module design and is unchanged in the C++26 draft.

open as a page

In C++20, how does a named module's interface unit differ from a header, and what can an importing file actually see?

level: middleimportance: should knowfreq 48%

basics

~20 s

A module interface unit is compiled once into a binary interface; an importer sees only its exported declarations, never its macros or unexported names, and the importer's own macros cannot change how the module was compiled.

open as a page

When a C++20 module mathlib is split into partitions, what must the primary interface do with them, and how do imports constrain build order?

level: seniorimportance: should knowfreq 28%

basics

~20 s

Every interface partition must be re-exported by the primary interface with export import :name; internal partitions stay private. Partitions are importable only inside their module, and since an importer needs each imported unit's BMI first, imports form an acyclic build order.

open as a page

Your team's C++ math library has many #include consumers; how do you decide whether and how to also ship it as a C++20 named module?

level: principalimportance: should knowfreq 30%

basics

~20 s

Adopt when every supported compiler and build system handles named modules; then ship a wrapper interface unit over the existing headers, export-using or extern "C++" style, so header and module users coexist and the symbol names stay unchanged.

open as a page