Modules¶

This library has experimental support for C++ modules, introduced in C++20. The library can be imported by writing import nlohmann.json; instead of #include <nlohmann/json.hpp>.

Please be aware that the module is experimental and a full test is outstanding, and the exported symbols are subject to change.

Importing the module instead of including the header reduces the compile time of every translation unit that uses the library, at the price of building the module once. The Compile times page has measurements and the one-off cost.

Requirements¶

The nlohmann.json module requires that the build system is configured to build and resolve modules when imported. Obviously, as modules were introduced in C++20, this feature can only be used in C++20 and subsequent versions.

To enable building the nlohmann.json module (which is not done by default), set the CMake option NLOHMANN_JSON_BUILD_MODULES and link the nlohmann_json_modules target.

With CMake, building the module needs:

• CMake 3.28 or newer, and
• a generator that scans for modules: Ninja (1.11 or newer), Ninja Multi-Config, or Visual Studio 2022 or newer.

The example below also uses import std;. CMake supports it without experimental opt-in since version 4.5, and then only with the Ninja generators and these toolchains: Clang 18.1.2 or newer (with libc++ or libstdc++), MSVC toolset 14.36 (Visual Studio 17.6) or newer, and GCC 15 or newer (GCC 16 on macOS). With older CMake versions, import std; needs CMake's version-specific experimental opt-in.

Example¶

When using modules rather than headers, the previous example for creating a json object through a JSON file, would instead be:

import std;
import nlohmann.json;

using nlohmann::json;

// ...

std::ifstream f("example.json");
json data = json::parse(f);

Modules do not export macros¶

It should be noted that as modules do not export macros, the nlohmann.json module will not export any macros.

Exported symbols¶

Only the following symbols are exported from nlohmann.json:

• nlohmann::adl_serializer
• nlohmann::basic_json
• nlohmann::basic_json_document
• nlohmann::basic_json_view
• nlohmann::is_json_view
• nlohmann::json
• nlohmann::json_document
• nlohmann::json_editable_document
• nlohmann::json_editable_view
• nlohmann::json_pointer
• nlohmann::json_view
• nlohmann::ordered_json
• nlohmann::ordered_json_document
• nlohmann::ordered_json_editable_document
• nlohmann::ordered_json_editable_view
• nlohmann::ordered_json_view
• nlohmann::ordered_map
• nlohmann::to_string
• nlohmann::view_mode
• nlohmann::literals::json_literals::operator""_json
• nlohmann::literals::json_literals::operator""_json_pointer

The module always exports the two user-defined string literals, even if JSON_NO_AUTOMATIC_UDLS is defined when building it.

Additionally, the following nlohmann::detail symbols are exported, solely to work around an MSVC compilation issue (#3970). They are implementation details, not part of the public API, and should not be used directly:

• nlohmann::detail::json_sax_dom_callback_parser
• nlohmann::detail::json_sax_dom_parser
• nlohmann::detail::unknown_size

Known issues¶

C++20 modules support is exercised in CI with CMake 4.5 and import std; against current GCC and Clang on Ubuntu, and the default MSVC toolset on Windows Server 2022 — there is no documented minimum compiler version, unlike feature-test-macro-gated features such as JSON_HAS_RANGES.

See also¶

• Supported Macros - macros are not exported by modules
• Macros - reference of all macros
• nlohmann Namespace - the library namespace
• CMake - enable the module build in CMake
• Compile times - reduce compile times
• basic_json - the main class and all its member functions