C++ Reference ยท Keywords and Statements
The import and module keywords
Reference for C++20 modules: module, export, import, global module fragment, partitions and header units, and how they replace #include.
A module is a unit of C++ code that you compile once and import by name, instead of pasting text with #include. The keywords are module (declares which module a file belongs to), export (makes a declaration visible to importers) and import (brings a module's exported names into the current file). Macros and non-exported names never leak out of a module, and importing is order-independent, which removes whole classes of header problems and can cut build times.
import and module are contextual keywords: they only have special meaning at the start of a declaration, so older code that uses them as identifiers still compiles in many cases. Modules need build-system support (the compiler must compile the module interface before its importers), which is the main practical obstacle.
// math.cppm (module interface unit) export module math; export int square(int x) { return x * x; } // main.cpp import math; int main() { return square(5); }
Try it
Our online runner compiles a single file, so it cannot build multi-file module setups and does not support import std;. The first example prints the module feature-test macro (GCC only defines __cpp_modules when modules are enabled, so the runner prints the fallback line) next to the traditional header approach that modules replace; the module code itself is shown read-only below.
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.
Read-only: a complete module on disk (not runnable here):
// shapes.cppm -- primary module interface unit module; // start of the global module fragment #include <cmath> // legacy headers go here export module shapes; // module declaration import <string>; // import a header unit (support varies) export namespace shapes { struct Circle { double r; }; inline double area(Circle c) { return 3.14159 * std::pow(c.r, 2); } } // not exported: invisible outside the module inline int helper() { return 1; }
// main.cpp import shapes; #include <iostream> int main() { shapes::Circle c{2.0}; std::cout << shapes::area(c) << '\n'; }
Compiling with GCC 15 needs the module interface first, for example g++ -std=c++23 -fmodules-ts -c shapes.cppm followed by g++ -std=c++23 -fmodules-ts main.cpp shapes.o. Real projects let CMake (3.28+) or another build system work out the order.
Syntax
module; // optional global module fragment (for #include) export module name; // primary interface unit export module name:partition; // interface partition module name:impl; // implementation partition module name; // implementation unit export declaration; // export one declaration export { declarations } // export a block export namespace ns { ... } // export a whole namespace export import other; // re-export another module import name; // import a module import :partition; // import a partition of the current module import <header>; // import a header unit module : private; // private module fragment
| Form | Meaning |
|---|---|
export module m; |
This file is the primary interface of module m. Only one per module. |
module m; |
An implementation unit: sees the interface, exports nothing. |
module m:p; / export module m:p; |
A partition, used to split a module internally. Interface partitions must be re-exported by the primary interface. |
import m; |
Makes the exported declarations of m visible, not its macros. |
import <h>; / import "h"; |
A header unit: a header compiled as if it were a module, which does export its macros. |
module : private; |
Everything after it is not part of the interface, so changing it does not force importers to rebuild. |
Errors / undefined behavior: importing a module that has not been built first is a compile error. Exporting a name with internal linkage, or exporting declarations from a non-interface unit, is ill-formed. Defining the same entity differently in two modules is an ODR violation (see ODR).
Usage notes
- Macros do not cross
import. If you need a macro, keep it in a header. Only header units pass macros. - Global module fragment. Put
#includeof legacy headers betweenmodule;and the module declaration so their contents are attached to the global module, not to yours. import std;(C++23) imports the whole standard library. It needs compiler and build-system support; it does not work on our runner.- Not a namespace. A module name groups code for compilation; use namespaces for naming. Exported names still live in whatever namespace you declare them in.
- Order independence. Unlike
#include,import a; import b;behaves the same in either order. - Build cost. The first build of a module is not faster, but each importing file avoids re-parsing the interface, which pays off in large projects.
- Compiler support is real but uneven: use recent GCC, Clang or MSVC with a module-aware build system.
Related
- Modules concept,
#include, Include guards,namespace - Lessons: C++20 Modules, Header files