Ideas: exploring ways to reduce compilation time

[nlohmann]

Status: brainstorming, not a plan

This is a collection of ideas for reducing compile-time overhead, written up so they are not lost. Nothing here is a sanctioned TODO or a commitment. Each item is a hypothesis to investigate, measure, and discuss before anything is decided. Some may turn out to be not worth it, break API/ABI, or conflict with the single-header philosophy. Treat this as a starting point for discussion.

Context / measurements

Some quick local measurements (single GCC machine, single-header, best of 3; absolute numbers are illustrative, not authoritative — they will differ per compiler/machine):

Scenario	C++11	C++17	C++20
#include <nlohmann/json.hpp> + empty main	~0.84s	~1.18s	~1.69s
…of which the ~44 pulled-in STL headers alone	~0.44s	~0.66s	~1.20s
Full parse + dump usage	~2.9s	~3.2s	—

Two observations worth keeping in mind when weighing ideas:

• There seem to be two separable costs: a fixed per-TU include cost (paid by any TU that includes the header) and a template-instantiation cost (paid per TU that actually uses conversions/parse/serialize, roughly a quarter of a usage build in -ftime-report).
• A large share of the include cost appears to come from the standard-library headers the header pulls in, not from our own code — and that share grows sharply at C++20.

Ideas (each unproven; needs measurement + discussion)

A. Trim/guard unconditional STL includes

• <valarray> and <forward_list> currently appear to be included unconditionally, solely to provide to_json/from_json overloads for those niche container types (detail/conversions/from_json.hpp, detail/conversions/to_json.hpp). Idea: guard those overloads (and their includes) behind an opt-in macro. Question to answer: how much does this actually save, and is silently dropping those overloads acceptable / how to make it discoverable?
• <any> seems to be pulled in for a single trait usage (around json.hpp is_same<ValueType, std::any>). Idea: investigate whether that check can be expressed without including <any>.
• The C++20-heavy includes (<format>, <ranges>, <any>) already look guarded behind feature macros — so likely little left to reclaim there, and the C++20 blow-up may be largely intrinsic. Worth confirming rather than assuming.

B. Optionally excluding the binary formats

• CBOR / MessagePack / BSON / UBJSON live in binary_reader.hpp (~3.1k lines) and binary_writer.hpp (~1.9k lines) — a sizeable fraction of the header that every TU compiles even when only text JSON is used. Idea: a JSON_NO_BINARY_FORMATS-style opt-out, analogous to the existing JSON_NO_IO.
• Caveat that makes this non-trivial: basic_json has friend/member-typedef coupling to those classes, so member functions would need guarding too, not just the includes. Needs a careful design sketch before it's even clear this is worth pursuing.

C. Better surface the existing json_fwd.hpp

• A forward-declaration header already exists but may be under-advertised. Idea: documentation/tutorial showing how to keep the full header out of widely-included headers (declare interfaces via json_fwd.hpp, include the full header only in .cpps). This is likely mostly a docs question rather than a code change, and could help the common "the header leaked into a common header and now recompiles everywhere" complaint.

D. Optional precompiled / extern-template path

• For the common default nlohmann::json specialization, idea: offer explicit instantiation declarations plus a single compiled TU, so the template-instantiation cost is paid once rather than per-TU (the "firewall" pattern people currently hand-roll). Open questions: maintenance burden, how it interacts with the header-only promise, whether it's opt-in only.

E. Longer-term: C++20 modules

• Idea / research direction only: a module interface could in principle remove much of the repeated header-parse cost. Realistically a large undertaking with fragile toolchain support today — noting it as a direction, not a near-term option.

Framing

Realistic goal, if any of this is pursued, would be materially lower fixed overhead, not parity with minimal/parser-focused libraries — that trade-off is inherent to being a single ergonomic header. Again: these are ideas to evaluate, not decisions.

[nlohmann]

Did some measuring on this. One concrete, non-breaking cleanup fell out, plus numbers for Idea A. g++ 13.3.0, -std=c++17 -O0, #include <nlohmann/json.hpp> + empty main, min-of-5.

New: <iomanip> is a dead include (ready to remove, non-breaking)

detail/output/serializer.hpp:21 includes <iomanip> // setfill, setw, but there is no iomanip manipulator used anywhere in the library — a word-boundary grep for setw|setfill|setprecision|setbase|setiosflags|resetiosflags|quoted|std::hex|std::oct|std::dec across include/nlohmann (excluding the vendored Hedley) matches only that #include line's own comment. A parse+dump usage TU compiles unchanged with the line deleted. It's also unconditional — even a JSON_NO_IO build pulls it in.

This is a straightforward removal, not a design idea like the rest of the list. Happy to send a one-line PR.

Numbers for Idea A (<valarray> / <forward_list> guarding)

Answering the "how much does this actually save?" question. Removing both <iomanip> (dead) and <valarray> (guarded behind an opt-in, as Idea A proposes):

	baseline	both removed
compile (empty TU)	0.97 s	0.905 s
preprocessed lines	116,327	112,886

So ~7% / ~67 ms of fixed per-TU include cost, ~3,400 preprocessed lines.

Worth flagging a measurement trap here: <valarray> and <iomanip> are ~31k and ~42k preprocessed lines standalone, but their marginal contribution to the header is only ~3.4k combined — because their heavy transitive deps (<string>, <algorithm>, locale bits) are already pulled in by the rest of the header. So the standalone header sizes overstate the win by ~20×; the marginal numbers above are the real ones. That also implies guarding the already-guarded C++20 headers further has little left to give, as the issue suspects.

Corroborating the two-cost split

Measured the include-cost half directly: a TU including just the ~19 core STL headers the library pulls (no nlohmann) is ~0.41 s, vs ~1.05 s for the full header — so of the fixed include cost, roughly 40% is parsing the STL headers and ~60% is parsing the library's own code (the basic_json class + the type_traits / from_json / to_json SFINAE overload sets). The header-trimming ideas (A) attack the 40%; the 60% is where a "reduce the overload sets" direction — collapsing the priority_tag ladders and detected_t chains in detail/meta/type_traits.hpp and the conversion headers — would help, though that's a much larger and riskier refactor than the include trimming, and separate from the per-TU instantiation cost you already noted dominates usage builds.

Repro harness available if useful.

---

Generated by Claude Code

[nlohmann]

Follow-up with the bigger lever — and a correction to one assumption in the issue.

The issue reasons that format/ranges/filesystem are "already guarded behind feature macros — so likely little left to reclaim there, and the C++20 blow-up may be largely intrinsic." Measuring it, that's not what happens: guarded-by-availability is not the same as off-by-default. JSON_HAS_FILESYSTEM, JSON_HAS_STD_FORMAT, and JSON_HAS_RANGES auto-define to 1 whenever the compiler has the feature — which, on any modern compiler, is always — so all three headers are pulled into every TU by default, for three niche features (path↔json conversion, a std::format formatter, ranges::enable_borrowed_range).

clang-18 -ftime-trace on #include <nlohmann/json.hpp> + empty main, C++17, ranks <filesystem> (via detail/meta/std_fs.hpp) as the single largest stdlib cost at ~188 ms — bigger than any of our own headers except json.hpp itself.

Measured savings from the existing opt-out macros (best-of-5, empty TU):

C++17

knob	gcc	clang
-DJSON_HAS_FILESYSTEM=0	−17% (177 ms)	−8% (99 ms)
+ <iomanip> (dead) + <valarray> guarded	—	−17% (215 ms)

C++20 (gcc, baseline 1.52 s)

knob	saving
-DJSON_HAS_STD_FORMAT=0	−17% (255 ms)
-DJSON_HAS_FILESYSTEM=0	−7% (106 ms)
-DJSON_HAS_RANGES=0	−6% (88 ms)
all three + <iomanip> + <valarray>	−36% (548 ms)

So the C++20 blow-up is largely not intrinsic — roughly a third of it is these three auto-on niche-feature headers, all already disable-able today.

Two concrete directions, both distinct from removing the dead <iomanip>:

1. Non-breaking, now: document the four macros as a "faster compiles" recipe (JSON_HAS_FILESYSTEM=0, JSON_HAS_STD_FORMAT=0, JSON_HAS_RANGES=0, plus whatever JSON_HAS_VALARRAY-style guard Idea A lands). They exist but are effectively undiscoverable as a compile-time knob — most users don't know they're paying 36% at C++20 for features they don't use. Perhaps also a single umbrella JSON_MINIMAL/JSON_NO_STD_INTEROP that flips all of them.
2. Breaking, major-version: reconsider whether the most expensive + most niche of these (the std::format formatter at −17%, and filesystem path conversion) should be opt-in rather than auto-on. ranges is cheaper and more load-bearing (borrowed-range correctness), so probably leave it.

Method note for reproducibility: these are marginal savings on the real header, not the standalone header sizes (which overstate ~20× because transitive deps are shared, as in my previous comment). Harness available.

---

Generated by Claude Code

[nlohmann]

New finding, and I think it's the biggest single fixed cost we have: the user-defined literals force the whole parser to be instantiated in every TU that includes the header, whether or not anyone uses them.

What happens

operator""_json and operator""_json_pointer (in json.hpp, namespace literals::json_literals) are non-template inline functions. Compilers semantically analyze the body of an inline function even if the function is never called, and any function template it odr-uses gets implicitly instantiated at the end of the TU. So operator""_json's body return nlohmann::json::parse(s, s + n); drags in basic_json<>::parse<const char*, const char*>, parser<…, iterator_input_adapter<const char*>>, the lexer, both json_sax_dom_parser and json_sax_dom_callback_parser, copy/destroy machinery, etc.

clang -ftime-trace on #include <nlohmann/json.hpp> + empty main (C++17) shows PerformPendingInstantiations = 275 ms of 748 ms total. The top entries are all from that chain (basic_json<>::parse<const char *, const char *, 0> 234 ms inclusive, sax_parse_internal<json_sax_dom_callback_parser…> 131 ms, …). With the four literal bodies removed, pending instantiations drop to 37 ms, and what's left is noise (concat, std::filesystem bits).

How much it costs

Removing only the four literal bodies (declarations kept), -O0 -c, min of 7–9 runs:

empty TU	clang 21 base	no UDL bodies	GCC 16 base	no UDL bodies
C++11	0.543 s	0.399 s (−27%)	0.583 s	0.404 s (−31%)
C++17	0.711 s	0.499 s (−30%)	0.759 s	0.562 s (−26%)
C++20	0.902 s	0.682 s (−24%)	0.971 s	0.756 s (−22%)

Where does this hit in practice? TUs that parse something themselves see ~0 difference, because their own parse() instantiation overlaps almost entirely with the literal's. The win is in TUs that include the header but don't parse: headers that hold json members, to_json/from_json definitions, code that passes json around. That's exactly the "header leaked into a common header" case. For example, a TU with just a NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE struct plus get<P>()/json(p) goes 0.83 → 0.69 s with clang (−16%) and 1.17 → 1.10 s with GCC (−6%).

Fix options

1. Non-breaking, ABI-identical, clang only: define the literals as friends of a class template. [over.literal] explicitly allows a literal operator to be a friend, and the definition of a friend in a class template is only instantiated when it's odr-used. Sketch:

   inline namespace json_literals {
   nlohmann::json operator""_json(const char* s, std::size_t n);   // for unqualified lookup
   // (same for _json_pointer and the char8_t overloads)
   
   template<typename Dummy = void>
   struct json_literal_definitions {
       using json_t = typename std::conditional<std::is_void<Dummy>::value, nlohmann::json, Dummy>::type;
       friend nlohmann::json operator""_json(const char* s, std::size_t n)
       { return json_t::parse(s, s + n); }
       // ...
   };
   static_assert(sizeof(json_literal_definitions<>) != 0, "");  // instantiate the class, not the bodies
   }

   With clang this recovers the full saving (empty TU C++17 0.715 → 0.510 s). It passes -Wall -Wextra -Wpedantic -Werror for C++11/14/17/20/23, handles using namespace nlohmann::literals, the global UDLs, u8 literals and explicit operator""_json(...) calls, and the mangled symbols are byte-identical to today's (…json_literalsli5_jsonEPKcm etc.).
   But GCC rejects it: GCC 12 and 16 both error with 'R lit::operator""_r(const char*, std::size_t)' has invalid argument list on any literal operator friend in a class template, dependent or not. I believe that's a GCC bug (clang accepts the same code in C++11 mode), but it means this only works as an #if defined(__clang__) path. MSVC is untested.

2. Non-breaking, portable: an opt-out macro (e.g. JSON_NO_UDLS, separate from the existing JSON_USE_GLOBAL_UDLS, which only controls the global using). It would go in the "faster compiles" recipe from my previous comment, next to JSON_HAS_FILESYSTEM=0 etc.

3. Breaking, major version: make the literals opt-in, e.g. move them to a separate <nlohmann/json_literals.hpp> (the amalgamated single header could keep including it unless JSON_NO_UDLS is set).

Things I tried that don't help: a leaner literal body that uses sax_parse with only json_sax_dom_parser (skipping the callback parser) saves ≤ 60 ms, within noise. The lexer/parser instantiation itself is the expensive part, and there's no portable way for a non-template function to reference a template without instantiating it.

Setup for these numbers: Apple M1 Max, Apple clang 21, Homebrew GCC 16.2, develop @ 373005f.

---

Written by Claude Code on behalf of @nlohmann

[nlohmann]

Numbers for the rest of the idea list. Same setup as the previous comment (Apple M1 Max, Apple clang 21, GCC 16.2, -O0 -c, min of 5–9 runs, develop @ 373005f).

A. <any>: not worth it

-DJSON_HAS_STATIC_RTTI=0 (the only thing that pulls in <any>) saves 8 ms with clang / 11 ms with GCC on an empty C++17 TU (~1.5–2%). <any>'s transitive deps are already there. Suggest dropping this bullet.

B. Excluding binary formats: little fixed-cost gain

In clang's -ftime-trace, parsing the class templates costs 9.1 ms for binary_reader and 5.6 ms for binary_writer (~15 ms, ~2% of an empty C++17 TU), even after BON8. Since they're templates, TUs that don't call to_cbor/from_msgpack/… never instantiate them, so a JSON_NO_BINARY_FORMATS switch would buy ~2% of fixed cost in exchange for the invasive basic_json surgery the issue describes. I'd deprioritize B.

C. json_fwd.hpp: worth advertising

empty C++17 TU	clang	GCC
#include <nlohmann/json_fwd.hpp>	0.326 s	0.239 s
#include <nlohmann/json.hpp>	0.708 s	0.760 s

So a header that only needs to name nlohmann::json saves 54% (clang) / 69% (GCC) per including TU by using json_fwd.hpp. That supports doing the docs work.

D. Extern template: works today, big win on GCC

template class nlohmann::basic_json<>; (explicit instantiation of the whole default specialization) compiles cleanly with clang and GCC in C++11/17/20. Putting extern template class nlohmann::basic_json<>; after the include in usage TUs and linking against that one TU works (tested parse → dump round trip):

TU	clang O0	+ extern	GCC O0	+ extern	GCC O2	+ extern
parse(stream) + dump	0.986	0.881 (−11%)	1.891	1.434 (−24%)	3.175	2.492 (−22%)
parse(string) + dump	0.937	0.866 (−8%)	1.825	1.413 (−23%)	3.120	2.372 (−24%)
to/from_json model	0.811	0.803 (−1%)	1.129	0.980 (−13%)	1.328	1.253 (−6%)

(Clang O2: −7…−9% on the parse TUs.) Together with the literal fix from my previous comment, the model TU reaches −18% on clang and −24% on GCC.

Caveats: only non-template members are covered. parse<InputType>, get<T>, and the conversion templates still instantiate per TU, which is why clang gains less. The instantiation TU is expensive (1.9 s clang / 5.0 s GCC), so for GCC it pays off after ~11 using TUs. Users can already do all of this today with no library change, so step one could be docs. Step two could be an opt-in helper, e.g. a JSON_EXTERN_TEMPLATE macro plus a documented one-line .cpp, which keeps the header-only promise. MSVC is untested.

E. C++20 modules: the module already exists and is by far the biggest lever

src/modules/json.cppm is already in the tree. With Homebrew LLVM clang 23.1 (Apple clang doesn't enable named modules), C++20:

TU	#include	import nlohmann.json;
empty	0.838 s	0.050 s (−94%)
parse(string) + dump	1.023 s	0.398 s (−61%)
to/from_json model	0.987 s	0.376 s (−62%)

One-time BMI build: 1.33 s, 30 MB .pcm.

With GCC 16.2 (-fmodules), an import-only TU goes 1.00 s → 0.07 s, but any #include <string>/<vector> in the same TU, whether before or after the import, fails with redefinition errors (std::__is_constant_evaluated, std::allocator). That's the #5103 problem, and it still reproduces on GCC 16.2, so on GCC the module is only usable together with import std; or in TUs that include nothing else from the standard library.

So E isn't a research direction anymore: on clang it already works and beats everything else combined. The work left is packaging, docs, and CI coverage rather than design.

Summary of where the fixed per-TU cost goes (clang, empty C++17 TU, ~0.71 s)

• ~210 ms: UDL-triggered parser instantiation (previous comment), fixable
• ~100 ms: <filesystem> auto-on (earlier comment, clang-18 figure; <format>/<ranges> add more at C++20), opt-out exists
• ~15 ms: binary reader/writer class parsing (B)
• ~8 ms: <any>
• remainder: core STL headers + parsing basic_json and the trait machinery

---

Written by Claude Code on behalf of @nlohmann

[gregmarr]

Have you tried making the user defined literal a template?

template<char... Arg>
nlohmann::json operator""_json() { return nlohmann::json::parse(Arg...); }

It does mean that there will be more of those functions instantiated, but hopefully those will mostly be inlined.

[nlohmann]

This comment was written by Claude Code.

@gregmarr Thanks, that goes after the right cost: the literal's body only gets compiled in files that use it. I tried it out:

• template<char...> doesn't work for string literals; that form only applies to numeric literals. "..."_json fails on both clang and GCC.
• template<typename C, C...> (the unadopted N3599 form) is a GNU extension. clang accepts it from C++11 with -Wgnu-string-literal-operator-template. GCC rejects it in C++11 and accepts it from C++14 with a -Wpedantic warning. MSVC doesn't support it.
• C++20 class-type template parameter (template<json_literal_string S> json operator""_json()) is the standard form and works on clang and GCC.

In every variant, the existing operator""_json(const char*, std::size_t) must be removed. Its inline body alone forces the parser to be compiled in every file. With both defined, which one gets called also differs by compiler: for the C++20 form, clang calls the template and GCC 16 calls the old function; for the GNU form, both call the old function. Removing it breaks code that calls operator""_json(s, n) directly or takes its address.

Measurements with the C++20 variant (Apple clang 21 / GCC 16.2, -std=c++20 -O0, median of 7):

File	clang	GCC 16
only #include <nlohmann/json.hpp>	943 → 844 ms (−10%)	1166 → 880 ms (−25%)
three _json literals	1128 → 1185 ms (+5%)	2003 → 2185 ms (+9%)

Downsides:

• Every distinct literal becomes its own function, and its symbol name contains the whole literal, one character at a time (Itanium mangling).
• Building the template's string at compile time hits clang's constexpr step limit. A ~1M-character literal fails with the default settings unless you raise -fconstexpr-steps. Today's header compiles it fine.

Covering all standards would take the C++20 template for C++20 and later, the GNU form (with the warning suppressed) for C++14/17 on GCC/clang, and the friend definition trick from above for clang in C++11. That's a lot of #ifs and per-compiler behavior for a ~10–25% saving that only matters in files that include the header but never parse.

I think a simpler route is a JSON_NO_UDLS opt-out macro that leaves out _json/_json_pointer entirely. It gets the full saving on every compiler and standard, doesn't change anything for users who don't set it, and code that doesn't use the literals (most model/header-only TUs) can turn it on right away. The literals themselves stay as they are.

[gregmarr]

I think a simpler route is a JSON_NO_UDLS opt-out macro that leaves out _json/_json_pointer entirely. It gets the full saving on every compiler and standard, doesn't change anything for users who don't set it, and code that doesn't use the literals (most model/header-only TUs) can turn it on right away. The literals themselves stay as they are.

Agreed, but I think we could combine it with sticking them in another header file that can be added after defining JSON_NO_UDLS before the include. Maybe JSON_NO_AUTOMATIC_UDLS so it doesn't sound like they can't be added on top.

inline namespace literals
{
inline namespace json_literals
{
}
}

Move all of this to nlohmann/json_literals.hpp, wrap it in the outer namespace there, and replace it with this:

#if !JSON_NO_AUTOMATIC_UDLS
#include <nlohmann/json_literals.hpp>
#endif