Skip to content
Tutorials Center
My learning

Topics

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.

C++
// 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.

C++ Detecting module support and the header approach it replaces

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):

C++
// 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; }
C++
// 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

C++
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 #include of legacy headers between module; 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.