C++ Reference ยท Types and Language Concepts
C++ modules
Concept page on C++20 modules: interface and implementation units, export and import, partitions, the global module fragment, header units and import std.
Modules (C++20) are a replacement for the #include model. A module is compiled once into a binary description of its exported declarations; other files import it by name. Nothing leaks out except what is marked export: macros defined inside a module are invisible to importers, and macros defined before an import do not change the module. Because importing does not paste text, the order of imports does not matter and build times can drop.
A module consists of one primary module interface unit (export module name;), optionally more partitions and implementation units (module name;). The standard library can be imported as import std; since C++23 (and import std.compat;). The language rules are stable, but build-system support is the practical hurdle: the compiler must compile the interface before any file that imports it.
On our runner: modules and import std; are not supported, because a program there is one source file compiled in a single step. The code below is shown read-only; the runnable examples show the problems modules solve.
// math.cppm export module math; export int square(int x) { return x * x; } // main.cpp import math; int main() { return square(5); }
Try it
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.
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.
Anatomy of a module
Read-only: three files that form one module.
// shapes.cppm -- primary module interface unit module; // global module fragment: legacy #includes go here #include <cmath> export module shapes; // the module declaration export namespace shapes { struct Circle { double r; }; double area(Circle c); // declared here, defined in an implementation unit } export import :units; // re-export a partition
// shapes_units.cppm -- partition export module shapes:units; export constexpr double inchToCm = 2.54;
// shapes.cpp -- implementation unit (does not export anything) module shapes; #include <numbers> double shapes::area(Circle c) { return std::numbers::pi * c.r * c.r; }
// main.cpp import shapes; import std; // C++23, where supported int main() { std::println("{:.2f}", shapes::area({2.0})); }
Pieces
| Piece | Meaning |
|---|---|
export module m; |
Starts the primary interface unit of module m. |
module m; |
Starts an implementation unit that sees m's interface but exports nothing. |
export |
Marks a declaration, a block export { ... } or a namespace as visible to importers. |
import m; |
Brings the exported names of m into this file. |
module; |
Starts the global module fragment for #include of legacy headers. |
module m:part; / import :part; |
Partitions: internal subdivisions of one module. |
import <header>; |
A header unit: a header imported as if it were a module (support and build setup vary). |
module :private; |
Private module fragment: put implementation in the interface file without exporting it. |
Usage notes
- File extensions are not standardized:
.cppm(Clang),.ixx(MSVC) or.cppall appear. The build system, not the extension, tells the compiler what to do. - Not exported does not mean not there. Non-exported entities still exist and may be reachable through exported inline functions or templates; they just cannot be named.
- Entities have module linkage by default, which sits between external and internal linkage. Two modules can each have a non-exported
helperwithout clashing. - No macros cross the boundary in either direction. If a legacy header needs a macro, put the
#defineand#includein the global module fragment or use a header unit. - ODR benefits: a module is defined once, so the One Definition Rule problems of duplicate class definitions in headers disappear for module code.
- Mixing worlds: you can
#includestandard headers in the global module fragment and still be a module. Migrating bit by bit is the normal path. - Tooling: CMake 3.28+ supports modules with
FILE_SET CXX_MODULESand a generator such as Ninja; GCC, Clang and MSVC all support them, withimport stdneeding recent toolchain versions. - Cyclic imports are errors. Break cycles with partitions or by moving shared types into a lower-level module.