json/docs/mkdocs/docs/integration/compile_times.md

Compile times

The library is header-only and makes heavy use of templates, so every translation unit that includes <nlohmann/json.hpp> pays for parsing the header and instantiating what it uses. This page lists the options to reduce that cost, ordered by how much they typically save.

!!! info "Measurements"

The numbers below are medians of the wall-clock time of nine runs compiling a single translation unit with
`-std=c++17 -c` against the single-header version, with Apple clang 21.0.0 (clang-2100.3.34.2) and Homebrew GCC
16.2.0 on macOS (Apple M1 Max). All configurations were run interleaved, in alternating order. They show the order
of magnitude to expect; measure your own code before and after a change.

The two sections on `std::format` and ranges apply to C++20 only and were measured with `-std=c++20`, so their
baselines are slower than the others. Their differences are mostly within the run-to-run noise of a few percent:
two complete runs of the same configuration differed by up to 10% in the median. The tables show the later run (one
outlier cell was repeated).

The translation units are listed below. They replace the ones used for earlier versions of this page, whose
sources were not published, so the numbers differ from earlier versions.

??? example "Measured translation units"

The *model* and *parsing* translation units start with `#include <string>`, `#include <vector>`, and
`#include <nlohmann/json.hpp>`; the *header-only* translation unit includes only the library header.

```cpp title="model translation unit"
struct person
{
    std::string name;
    int age = 0;
    std::vector<std::string> tags;
};

void to_json(nlohmann::json& j, const person& p)
{
    j = nlohmann::json{{"name", p.name}, {"age", p.age}, {"tags", p.tags}};
}

void from_json(const nlohmann::json& j, person& p)
{
    j.at("name").get_to(p.name);
    j.at("age").get_to(p.age);
    j.at("tags").get_to(p.tags);
}

nlohmann::json roundtrip(const person& p)
{
    nlohmann::json j = p;
    return nlohmann::json(j.get<person>());
}
```

```cpp title="parsing translation unit"
std::size_t parse_and_dump(const std::string& s)
{
    const nlohmann::json j = nlohmann::json::parse(s);
    return j.dump(2).size();
}
```

```cpp title="header-only translation unit"
#include <nlohmann/json.hpp> // or <nlohmann/json_fwd.hpp>

struct person;
void to_json(nlohmann::json& j, const person& p);
void from_json(const nlohmann::json& j, person& p);
```

--8<-- "images/compile_times.svg"

Change in compile time at `-O0` against the default configuration of the same translation unit, taken from the tables below (medians of nine runs, see above; the `std::format` and ranges rows are measured with `-std=c++20`). * computed from the milliseconds in [Options without effect on compile times](#options-without-effect-on-compile-times).

Include json_fwd.hpp in headers

Header files that only need to name the json type — for function declarations, members held by pointer or reference, or friend declarations — can include <nlohmann/json_fwd.hpp> instead of <nlohmann/json.hpp>. It only forward-declares basic_json, json_pointer, adl_serializer, and ordered_map, and defines the aliases json and ordered_json. The translation units that actually use the values then include <nlohmann/json.hpp>.

#pragma once
#include <nlohmann/json_fwd.hpp>

struct person;
void to_json(nlohmann::json& j, const person& p);
void from_json(const nlohmann::json& j, person& p);

#include "person.hpp"
#include <nlohmann/json.hpp>

void to_json(nlohmann::json& j, const person& p) { /* ... */ }
void from_json(const nlohmann::json& j, person& p) { /* ... */ }

Compiler	json.hpp (-O0)	json_fwd.hpp (-O0)	Change
Apple clang	868 ms	332 ms	−62%
GCC 16	1164 ms	210 ms	−82%

Compile time of the header-only translation unit at `-O0` with each header, as the median wall-clock time of nine runs (see "Measurements" above). A negative change means a faster build.

This is the most effective option, because it avoids the full header in every translation unit that includes your headers.

Opt out of the automatic user-defined string literals

The user-defined string literals operator""_json and operator""_json_pointer are ordinary inline functions whose bodies call the parser. As <nlohmann/json.hpp> includes them by default, every translation unit instantiates the parser, even if it never parses anything itself.

Define JSON_NO_AUTOMATIC_UDLS for the whole project and include <nlohmann/json_literals.hpp> instead of <nlohmann/json.hpp> in the files that use the literals (it includes <nlohmann/json.hpp> itself):

target_compile_definitions(my_target PRIVATE JSON_NO_AUTOMATIC_UDLS)

#include <nlohmann/json_literals.hpp> // only where "..."_json is used; includes <nlohmann/json.hpp>

The saving applies to translation units that do not parse JSON, for example ones that define types and their conversions or only pass json values around:

Compiler	Translation unit	Default (-O0 / -O2)	JSON_NO_AUTOMATIC_UDLS (-O0 / -O2)	Change
Apple clang	model	1051 ms / 1300 ms	935 ms / 1170 ms	−11% / −10%
GCC 16	model	1801 ms / 2106 ms	1598 ms / 1983 ms	−11% / −6%
Apple clang	parsing	1157 ms / 2016 ms	1146 ms / 2006 ms	−1% / 0%
GCC 16	parsing	2529 ms / 4087 ms	2484 ms / 4059 ms	−2% / −1%

Compile time of the model and parsing translation units without and with `JSON_NO_AUTOMATIC_UDLS`, at `-O0` and `-O2`.

The model translation unit saves about a tenth. Translation units that parse anyway instantiate the parser regardless and see no difference.

Instantiate basic_json once

Each translation unit instantiates the member functions of nlohmann::json it uses. An explicit instantiation declaration tells the compiler that the non-template members are instantiated elsewhere, so it can skip them:

#pragma once
#include <nlohmann/json.hpp>

extern template class nlohmann::basic_json<>;

#include "json_instance.hpp"

template class nlohmann::basic_json<>;

Include json_instance.hpp instead of <nlohmann/json.hpp> and compile and link json_instance.cpp once.

Compiler	Translation unit	Default (-O0 / -O2)	extern template (-O0 / -O2)	Change
Apple clang	parsing	1157 ms / 2016 ms	1071 ms / 1844 ms	−7% / −9%
GCC 16	parsing	2529 ms / 4087 ms	1994 ms / 3190 ms	−21% / −22%
Apple clang	json_instance.cpp	—	2573 ms / 6221 ms	—
GCC 16	json_instance.cpp	—	6489 ms / 13759 ms	—

Compile time of the parsing translation unit without and with the `extern template` declaration, at `-O0` and `-O2`. The `json_instance.cpp` rows are the one-off cost of the translation unit that holds the instantiation.

Notes:

• The saving grows with the number of translation units that use json, while the instantiation translation unit is compiled only once (and is rarely recompiled, as it does not depend on your code).
• Member function templates (such as get<T>(), parse(InputType&&), or value(key, default)) are not covered by the explicit instantiation and are still instantiated where they are used.
• The declaration covers exactly nlohmann::json. Add the same lines for nlohmann::ordered_json (nlohmann::basic_json<nlohmann::ordered_map>) or your own basic_json specializations if you use them.

Switch off filesystem support

With C++17, the library includes <filesystem> to provide conversions from and to std::filesystem::path (see JSON_HAS_FILESYSTEM). Parsing <filesystem> is a fixed cost in every translation unit, and it also pulls in <iomanip>, <istream>, and <ostream> (and, with GCC's libstdc++, <sstream>). If you do not convert paths, switch the detection off for the whole project:

target_compile_definitions(my_target PRIVATE JSON_HAS_FILESYSTEM=0 JSON_HAS_EXPERIMENTAL_FILESYSTEM=0)

Compiler	Translation unit	Default (-O0 / -O2)	Filesystem off (-O0 / -O2)	Change
Apple clang	model	1051 ms / 1300 ms	998 ms / 1257 ms	−5% / −3%
GCC 16	model	1801 ms / 2106 ms	1636 ms / 2008 ms	−9% / −5%
Apple clang	parsing	1157 ms / 2016 ms	1107 ms / 1971 ms	−4% / −2%
GCC 16	parsing	2529 ms / 4087 ms	2405 ms / 4029 ms	−5% / −1%

Compile time with `JSON_HAS_FILESYSTEM=0` and `JSON_HAS_EXPERIMENTAL_FILESYSTEM=0` against the default configuration, at `-O0` and `-O2`.

Only with filesystem support switched off does JSON_NO_IO remove the stream headers from the translation unit, so the two macros save most together:

Compiler	Translation unit	Default (-O0 / -O2)	Filesystem off and JSON_NO_IO (-O0 / -O2)	Change
Apple clang	model	1051 ms / 1300 ms	969 ms / 1219 ms	−8% / −6%
GCC 16	model	1801 ms / 2106 ms	1605 ms / 1982 ms	−11% / −6%
Apple clang	parsing	1157 ms / 2016 ms	1083 ms / 1947 ms	−6% / −3%
GCC 16	parsing	2529 ms / 4087 ms	2384 ms / 3972 ms	−6% / −3%

Compile time with filesystem support switched off and `JSON_NO_IO` defined, against the default configuration, at `-O0` and `-O2`.

The trade-off: the library's own to_json/from_json overloads for std::filesystem::path (which store the path as UTF-8) are removed. In a test with both compilers on macOS, paths still converted through their implicit conversion from and to std::string; whether that fallback exists depends on the platform's native path string type (std::wstring on Windows), so check code that converts paths. JSON_NO_IO additionally removes all stream functions (see Options without effect).

Switch off std::format support

With C++20 and a standard library that provides <format>, the library includes it to provide a std::formatter<basic_json> specialization (see JSON_HAS_STD_FORMAT). If you do not format JSON values with std::format, switch the detection off for the whole project:

target_compile_definitions(my_target PRIVATE JSON_HAS_STD_FORMAT=0)

Compiler	Translation unit	Default (-O0 / -O2)	std::format off (-O0 / -O2)	Change
Apple clang	model	1283 ms / 1544 ms	1269 ms / 1539 ms	−1% / 0%
GCC 16	model	2026 ms / 2482 ms	1944 ms / 2416 ms	−4% / −3%
Apple clang	parsing	1350 ms / 2278 ms	1347 ms / 2300 ms	0% / +1%
GCC 16	parsing	2715 ms / 4351 ms	2644 ms / 4287 ms	−3% / −1%

Compile time with `JSON_HAS_STD_FORMAT=0` against the default configuration, both with `-std=c++20`, at `-O0` and `-O2`.

The saving is small, and only GCC shows it: libstdc++'s <format> is an additional header that nothing else in the translation unit includes, so the macro removes it (and the headers it pulls in). With libc++ (Apple clang), other standard headers include <format> anyway, so the macro only removes the library's own formatter, and the difference is within the noise.

The trade-off: the std::formatter<basic_json> specialization is removed, so #!cpp std::format("{}", j), and #!cpp std::format_to with a JSON value no longer compile (in a test with both compilers on macOS, the error was that std::formatter must be specialized for the type). Use dump(), or the stream operators, instead.

Switch off ranges support

With C++20 and a standard library that provides <ranges>, the library includes it to declare the items() proxy a borrowed range, and uses the std::ranges concepts and algorithms for construction from range views and for iterator input (see JSON_HAS_RANGES). If you do not need these, switch the detection off for the whole project:

target_compile_definitions(my_target PRIVATE JSON_HAS_RANGES=0)

Compiler	Translation unit	Default (-O0 / -O2)	Ranges off (-O0 / -O2)	Change
Apple clang	model	1283 ms / 1544 ms	1237 ms / 1495 ms	−4% / −3%
GCC 16	model	2026 ms / 2482 ms	2004 ms / 2464 ms	−1% / −1%
Apple clang	parsing	1350 ms / 2278 ms	1311 ms / 2284 ms	−3% / 0%
GCC 16	parsing	2715 ms / 4351 ms	2705 ms / 4427 ms	0% / +2%

Compile time with `JSON_HAS_RANGES=0` against the default configuration, both with `-std=c++20`, at `-O0` and `-O2`.

The saving is small as well, and with GCC it is not distinguishable from the noise: its <format> includes <span>, so with std::format support left on, part of the ranges machinery is still parsed. Both macros together save more than either alone:

target_compile_definitions(my_target PRIVATE JSON_HAS_STD_FORMAT=0 JSON_HAS_RANGES=0)

Compiler	Translation unit	Default (-O0 / -O2)	Both off (-O0 / -O2)	Change
Apple clang	model	1283 ms / 1544 ms	1223 ms / 1504 ms	−5% / −3%
GCC 16	model	2026 ms / 2482 ms	1914 ms / 2378 ms	−6% / −4%
Apple clang	parsing	1350 ms / 2278 ms	1311 ms / 2271 ms	−3% / 0%
GCC 16	parsing	2715 ms / 4351 ms	2635 ms / 4260 ms	−3% / −2%

Compile time with `JSON_HAS_STD_FORMAT=0` and `JSON_HAS_RANGES=0` against the default configuration, both with `-std=c++20`, at `-O0` and `-O2`.

The trade-offs of JSON_HAS_RANGES=0 are larger than those of the other options on this page:

• items() is no longer a borrowed range. On a temporary, #!cpp std::ranges::begin(make_json().items()) no longer compiles, and std::ranges algorithms such as #!cpp std::ranges::find_if(make_json().items(), pred) return std::ranges::dangling instead of an iterator, so code that uses the result no longer compiles. Calling them on #!cpp j.items() for a named j is not affected.
• JSON_HAS_RANGE_VIEW_CONVERSION becomes 0, so a JSON array can no longer be constructed from a std::ranges::view such as the result of std::views::filter. The assignment #!cpp json j = v | std::views::filter(pred); no longer compiles.
• Parsing from an iterator pair loses the C++20 fast path for contiguous iterators that are not pointers (for example those of std::vector) and falls back to byte-at-a-time scanning. The result is the same; parsing may be slower (not measured here).

The first two were checked with both compilers on macOS; the third is read from the library's source.

Use C++20 modules

With a toolchain that supports named modules, import nlohmann.json; compiles the library once into a module and avoids parsing the header in every translation unit. See Modules for requirements and known issues. Module support is experimental and currently depends heavily on the compiler version.

--8<-- "images/compile_times_modules.svg"

Change in compile time per translation unit at `-O0` when `#include <nlohmann/json.hpp>` is replaced by `import nlohmann.json;`, both with `-std=c++20`, and the one-off cost of building the module, taken from the table below.

Compiler	Translation unit	#include (-O0 / -O2)	import nlohmann.json; (-O0 / -O2)	Change
Apple clang	model	1311 ms / 1597 ms	680 ms / 914 ms	−48% / −43%
GCC 16	model	2156 ms / 2588 ms	1153 ms / 1580 ms	−47% / −39%
Apple clang	parsing	1387 ms / 2319 ms	800 ms / 1676 ms	−42% / −28%
GCC 16	parsing	2838 ms / 4520 ms	1810 ms / 3476 ms	−36% / −23%
Apple clang	json.cppm (module)	—	1630 ms / 1642 ms	—
GCC 16	json.cppm (module)	—	2538 ms / 2547 ms	—

Compile time with `#include <nlohmann/json.hpp>` and with `import nlohmann.json;`, both with `-std=c++20`, at `-O0` and `-O2`. The `json.cppm` rows are the one-off cost of building the module.

Both columns use -std=c++20; with -std=c++17, the #include baseline is 17% to 20% faster (see the next section). The module is built once per set of compiler flags and pays for itself from about the third translation unit that imports it. Notes from the measurement:

• Apple clang only accepts the module declarations with -fcxx-modules; without it, module; is a syntax error.
• GCC 16 warns with -Wexpose-global-module-tu-local about internal constants of the library when building the module. With GCC 16.2, including <string> and <vector> before import nlohmann.json; works, but including them after it fails with redefinition errors (#5103).

??? example "How these numbers were measured"

The model and parsing translation units are the ones listed at the top of this page, with `import nlohmann.json;`
in place of `#include <nlohmann/json.hpp>` (after `#include <string>` and `#include <vector>`). Same method as
for the other tables, with `-std=c++20`.

```sh
# Apple clang: build the module once, then import it
clang++ -std=c++20 -fcxx-modules -O0 -I single_include -c -x c++-module src/modules/json.cppm \
    -fmodule-output=nlohmann.json.pcm -o json_mod.o
clang++ -std=c++20 -fcxx-modules -O0 -fmodule-file=nlohmann.json=nlohmann.json.pcm -c model.cpp

# GCC 16 (Homebrew on macOS): writes gcm.cache/nlohmann.json.gcm, found by the importing translation unit
g++-16 --sysroot=$(xcrun --show-sdk-path) -std=c++20 -fmodules -O0 -I single_include -c src/modules/json.cppm \
    -o json_mod.o
g++-16 --sysroot=$(xcrun --show-sdk-path) -std=c++20 -fmodules -O0 -c model.cpp
```

Link `json_mod.o` into the program.

Use precompiled headers

Build systems can precompile <nlohmann/json.hpp> together with other stable headers, for example with CMake's target_precompile_headers:

target_precompile_headers(my_target PRIVATE <nlohmann/json.hpp>)

This removes the cost of parsing the header, but not of instantiating templates in each translation unit, so it combines well with the options above.

--8<-- "images/compile_times_pch.svg"

Change in compile time per translation unit at `-O0` with a precompiled `<nlohmann/json.hpp>` (`-std=c++17`), and the one-off cost of building the precompiled header, taken from the table below.

Compiler	Translation unit	Default (-O0 / -O2)	With PCH (-O0 / -O2)	Change
Apple clang	model	1045 ms / 1295 ms	594 ms / 842 ms	−43% / −35%
GCC 16	model	1789 ms / 2101 ms	1060 ms / 1376 ms	−41% / −35%
Apple clang	parsing	1148 ms / 2008 ms	714 ms / 1584 ms	−38% / −21%
GCC 16	parsing	2498 ms / 4075 ms	1884 ms / 3452 ms	−25% / −15%
Apple clang	building the PCH	—	771 ms / 760 ms	—
GCC 16	building the PCH	—	2254 ms / 2218 ms	—

Compile time without and with a precompiled `<nlohmann/json.hpp>`, at `-O0` and `-O2`. The last two rows are the one-off cost of building the precompiled header.

The saving is largest in translation units that instantiate little, and the PCH pays for itself from the second (Apple clang) or fourth (GCC) translation unit. A precompiled header only works with the flags it was built with: GCC silently ignores a mismatching .gch file (for example one built with another -O level) unless -Winvalid-pch is given.

??? example "How these numbers were measured"

`pch.hpp` contains only `#include <nlohmann/json.hpp>`; the translation units are the ones
listed at the top of this page.

```sh
# Apple clang
clang++ -std=c++17 -O0 -I single_include -x c++-header pch.hpp -o pch.hpp.pch
clang++ -std=c++17 -O0 -I single_include -include-pch pch.hpp.pch -include pch.hpp -c model.cpp

# GCC 16 (Homebrew on macOS): pch.hpp.gch next to pch.hpp is picked up by -include pch.hpp
g++-16 --sysroot=$(xcrun --show-sdk-path) -std=c++17 -O0 -I single_include -x c++-header pch.hpp -o pch.hpp.gch
g++-16 --sysroot=$(xcrun --show-sdk-path) -std=c++17 -O0 -I single_include -include pch.hpp -Winvalid-pch -c model.cpp
```

Options without effect on compile times

Some configuration macros change what the library declares, but do not measurably change compile times:

Macro	Apple clang, model (-O0 / -O2)	GCC 16, model (-O0 / -O2)
default	1051 ms / 1300 ms	1801 ms / 2106 ms
JSON_NO_IO	1034 ms / 1288 ms	1756 ms / 2087 ms
JSON_USE_GLOBAL_UDLS=0	1055 ms / 1298 ms	1783 ms / 2109 ms

Compile time of the model translation unit with each macro defined; the first row is the default configuration for comparison.

JSON_NO_IO removes the library's stream functions and its #includes of <istream> and <ostream>, but with the default C++17 settings <filesystem> includes these headers anyway (and with libc++, <vector> already includes <streambuf> via <locale>), so only a few hundred lines of the library's own stream code go away. It also does not change what the translation unit instantiates. On the parsing translation unit, the change is 0% / 0% (Apple clang) and −2% / 0% (GCC). To get a saving, combine it with switching off filesystem support.

JSON_USE_GLOBAL_UDLS only controls where the literals are declared; to avoid their cost, use JSON_NO_AUTOMATIC_UDLS instead.

See also

• JSON_HAS_FILESYSTEM - control the conversions from and to std::filesystem::path
• JSON_HAS_STD_FORMAT - control the std::formatter specialization
• JSON_HAS_RANGES - control the use of std::ranges
• JSON_NO_AUTOMATIC_UDLS - do not include the user-defined string literals automatically
• Modules - C++20 module support
• Header only - including the library
• Macros - reference of all macros
• Supported Macros - overview of all configuration macros
• Performance - run-time performance
• JSON_NO_IO - remove all stream and file I/O