# 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](../integration/compile_times.md#use-c20-modules) 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`](../integration/cmake.md#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:
```cpp
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`](../api/macros/json_no_automatic_udls.md) is defined when building it.

Additionally, the following `nlohmann::detail` symbols are exported, solely to work around an MSVC compilation issue
([#3970](https://github.com/nlohmann/json/issues/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`](../api/macros/json_has_ranges.md).

!!! info "Known compiler issues"

    - **GCC** may emit "redefinition" errors when `#include <nlohmann/json.hpp>` appears in a module preamble together with other imports. This is an upstream GCC bug, not yet resolved as of GCC 16. Workarounds: include `nlohmann/json.hpp` before other `#include`s, use `import nlohmann.json;` instead, or upgrade GCC. ([issue #5103](https://github.com/nlohmann/json/issues/5103))
    - **MSVC** could fail with `C2039: 'json_sax_dom_callback_parser' is not a member of ... detail`; fixed by exporting the required internal symbols from `json.cppm` (see [Exported symbols](#exported-symbols) above). ([issue #3970](https://github.com/nlohmann/json/issues/3970))

    If you hit a different module-related build failure, search [existing issues](https://github.com/nlohmann/json/issues?q=is%3Aissue+modules) before filing a new one.

## See also

- [Supported Macros](macros.md) - macros are not exported by modules
- [Macros](../api/macros/index.md) - reference of all macros
- [`nlohmann` Namespace](namespace.md) - the library namespace
- [CMake](../integration/cmake.md) - enable the module build in CMake
- [Compile times](../integration/compile_times.md) - reduce compile times
- [`basic_json`](../api/basic_json/index.md) - the main class and all its member functions