• Comment: Some large sections of unsourced text. Encoded  Talk ?? 22:01, 26 June 2025 (UTC)
• Comment: (In response) I have reworded many parts of the article to be less essay-like and added official ISO C++ specification citations wherever applicable, I think it is adequately sourced now. 24.50.56.74 (talk) 23:17, 24 July 2025 (UTC)

---

百度 真抓的实劲“抓落实来不得花拳绣腿，光喊口号、不行动不行”“只有干出来的精彩，没有编出来的辉煌。

Modules in C++ are a modular programming feature added in C++20 as a modern alternative to precompiled headers. A module in C++ comprises a single translation unit. Like header files and implementation files, a module can contain declarations and definitions, but differ from precompiled headers in that they do not require the preprocessor directive #include, but rather are accessed using the word import. A module must be declared using the word module to indicate that the translation unit is a module. A module, once compiled, is stored as a .pcm (precompiled module) file which acts very similar to a .pch (precompiled header) file.

Modules most commonly have the extension .cppm (primarily common within Clang and GCC toolchains), though some alternative extensions include .ixx and .mxx (more common in Microsoft/MSVC toolchains).

Though the standard C language does not have modules, dialects of C allow for modules, such as Clang C. However, the syntax and semantics of Clang C modules differ from C++ modules significantly.

Main uses

Modules provide the benefits of precompiled headers of faster compilation than #included traditional headers, as well as and faster processing during the linking phase. This is because modules are not handled by the C preprocessor during the preprocessing step, but rather directly by the compiler during compilation. Modules also reduce boilerplate by allowing code to be implemented in a single file, rather than being separated across a header file and source implementation, although separation of "interface file" and "implementation file" is still possible with modules. Modules eliminate the necessity of #include guards or #pragma once, as modules do not directly modify the source code. Modules, unlike headers, do not have to be processed or recompiled multiple times. However, similar to headers, any change in a module necessitates the recompilation of not only the module itself but also all its dependencies, and the dependencies of those dependencies, et cetera. Like headers, modules do not permit circular dependencies, and will not compile.

A module is imported using the keyword import followed by a module name, while a module is declared with export module followed by the name. All symbols within a module meant to be exposed publicly are marked export, and importing the module exposes all exported symbols to the translation unit. If a module is never imported, it will never be linked. Modules can export named symbols, but not macros which are consumed before compilation.

Unlike header inclusions, the order of import statements do not matter. A module can allow for transitive imports by marking an import with export import, which re-exports the imported module to a translation unit that imports the first module. Modules do not enforce any notion of namespaces, but it is not uncommon to see projects manually associate modules to namespaces (for example, a namespace like exampleproj::util::contents being tied to the module exampleproj.util.contents). Because using statements will not be included into importing files (unless explicitly marked export), it is much less likely that using a using statement to bring symbols into the global namespace will cause name clashes within module translation units.

Currently, only GCC, Clang, and MSVC offer support for modules.

Standard library modules

Since C++23, the C++ standard library has been exported as a module as well, though as of currently it must be imported in its entirety (using import std;). The C++ standards offer two standard library modules:

Name	Description
std	Exports all declarations in namespace std and global storage allocation and deallocation functions that are provided by the importable C++ library headers including C library facilities (although declared in standard namespace).
std.compat	Exports the same declarations as the named module std, and additionally exports functions in global namespace in C library facilities. It thus contains "compat" in the name, meaning compatibility with C.

The module names std and std.* are reserved by the C++ standard, and thus declaring a module whose name matches either pattern will issue a compiler warning. However, most compilers provide a flag to bypass or suppress that warning (for example -Wno-reserved-module-identifier in Clang and GCC).

Currently, only GCC, Clang, and MSVC support standard library modules.

Example

A simple example of using modules is as follows:

MyClass.cppm

export module myproject.MyClass;

import std;

export namespace myproject {

class MyClass {
private:
    int x;
    std::string name;
public:
    MyClass(int x, const std::string& name):
        x{x}, name{name} {}

    [[nodiscard]]
    int getX() const noexcept {
        return x;
    }

    void setX(int newX) noexcept {
        x = newX;
    };

    [[nodiscard]]
    std::string getName() const noexcept {
        return name;
    }

    void setName(const std::string& newName) noexcept {
        name = newName;
    }
};

}

Main.cpp

import std;

import myproject.MyClass;

using myproject::MyClass;

int main(int argc, char* argv[]) {
    MyClass me(10, "MyName");
    me.setX(15);
    std::println("Hello, {0}! {0} contains value {1}.", me.getName(), me.getX());
}

Header units

Headers may also be imported using import, even if they are not declared as modules. Imported headers are called "header units", and are designed to allow existing codebases to migrate from headers to modules more gradually. The syntax is similar to including a header, with the difference being that #include is replaced with import. As import statements are not preprocessor directives but rather full statements of the language read by the compiler, they must be terminated by a semicolon. Header units automatically export all symbols, and differ from proper modules in that they allow the emittance of macros, meaning all translation units that import the header unit will obtain its contained macros. This offers minimal breakage between migration to modules. The semantics of searching for the file depending on whether quotation marks or angle brackets are used apply here as well. For instance, one may write import <string>; to import the <string> header, or import "MyHeader.h"; to import the file "MyHeader.h" as a header unit. Most build systems, such as CMake, do not support this feature yet.

Anatomy

Module partitions and hierarchy

Modules may have partitions, which separate the implementation of the module across several files. Module partitions are declared using the syntax A:B, meaning the module A has the partition B. Module partitions cannot individually be imported outside of the module that owns the partition itself, meaning that any translation unit that requires code located in a module partition must import the entire module that owns the partition.

The module partition B is linked back to the owning module A with the statement import :B; in the file containing the declaration of module A or any other module partition of A (say A:C), which implicitly resolves :B to A:B, because the module is named A. These import statements may themselves be exported by the owning module, even if the partition itself cannot be imported directly, and thus importing code from a partition is done by just importing the entire module.

Other than partitions, modules do not have a hierarchical system or "submodules", but typically use a hierarchical naming convention, similar to Java's packages. Only alphanumeric characters and the period and underscore may appear in the name of a module. In C++, the name of a module is not tied to the name of its file or the module's location, unlike in Java, and the package it belongs to must match the path it is located in. For example, the modules A and A.B in theory are disjoint modules and need not necessarily have any relation, however such a naming scheme is often employed to suggest that the module A.B is somehow related or otherwise associated with the module A.

The naming scheme of a C++ module is inherently hierarchical, and the C++ standard recommends re-exporting "sub-modules" belonging to the same public API (i.e. module alpha.beta.gamma should be re-exported by alpha.beta, etc.), even though dots in module names do not enforce any hierarchy. The C++ standard recommends lower-case ASCII module names (without hyphens or underscores), even though there is technically no restriction in such names. Also, because modules cannot be re-aliased or renamed (short of re-exporting all symbols in another module), module names can be prefixed with organisation/project names for both clarity and to prevent naming clashes (i.e. google.abseil instead of abseil). Also, unlike Java, whose packages may typically include a TLD to avoid namespace clashes, C++ modules need not have this convention.

Module purview and global module fragment

In the above example, everything above the line export module myproject.MyClass; in the file MyClass.cppm is referred to as what is "outside the module purview", meaning what is outside of the scope of the module. Typically, if headers must be included, all #includes are placed outside the module purview between a line containing only the statement module; and the declaration of export module, like so:

module; // Optional; marks the beginning of the global module fragment (mandatory if an include directive is invoked above the export module declaration)

// Headers are included in outside the module purview, before the module is declared
#include <print>
#include "MyHeader.h"

export module myproject.MyModule; // Mandatory; marks the beginning of the module preamble

// Imports of named modules and header units come after the module declaration
// Import statements must be placed immediately after the module declaration and cannot come after any code or symbol declarations
// In non-module translation units, #include directives must precede import statements
import std;
import <string>;
import myproject.util.UtilitySymbols;
import "Foo.h";
import <thirdlib/features/Feature.h>;

// Code here...

module: private; // Optional; marks the beginning of the private module fragment

All code which does not belong to any module exists in the so-called "unnamed module" (also known as the global module fragment), and thus cannot be imported by any module.

The file containing main() may declare a module, but typically it does not (as it is unusual to export main() as it is typically only used as an entry point to the program, and thus the file is usually a .cpp file and not a .cppm file). A program is ill-formed if it exports main() and doing so causes undefined behaviour, but will not necessarily be rejected by the compiler.

Private module fragment

A module may declare a "private module fragment" by writing module: private;, in which all declarations or definitions after the line are visible only from within the file and cannot be accessed by translation units that import that module. Any module unit that contains a private module fragment must be the only module unit of its module.

See also

• Precompiled header
• Prefix header
• Single compilation unit
• Java package
• Java Platform Module System