# nlohmann/json: a single-header JSON library for C++ that trades speed for integration

> nlohmann/json puts JSON into C++ as a first-class value type through one header file, json.hpp. It is the right default when you want to parse, build and serialize JSON without adding a build dependency, and the wrong one when parsing throughput is the bottleneck.

**nlohmann/json** — JSON for Modern C++ is a header-only library that makes JSON feel like a first-class data type in C++, with STL-like access plus support for CBOR, BSON, and MessagePack.

- Repository: https://github.com/nlohmann/json
- Website: https://json.nlohmann.me
- Stars: 50,687 · Forks: 7,510
- Language: C++
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/nlohmann-json

## What nlohmann/json actually solves for C++ projects

C++ has no JSON type in the standard library. Before a library like this, adding JSON to a program meant either writing a parser by hand or adopting a parser whose API forced you to walk a tree of node pointers and check types at every step. nlohmann/json's stated design goal is to make JSON feel like a first-class data type, using operator overloading so that a json value behaves close to how a dict or list behaves in Python or JavaScript. The second goal is trivial integration: the whole library is a single header file, json.hpp, written in vanilla C++11, with no library, subproject, dependencies or complex build system. That combination is the product. It is aimed at application developers who need configuration files, HTTP payloads, or inter-process messages and do not want the JSON layer to become a build engineering project. The README is direct about the trade: memory efficiency and speed were not priorities, and it points readers to faster JSON libraries if speed is the goal.

## How the single header and basic_json fit together

The repository keeps its sources under include/ and amalgamates them into single_include/nlohmann/json.hpp, with a forward-declaration-only companion at single_include/nlohmann/json_fwd.hpp. The Makefile documents an amalgamate target that regenerates those files from include/nlohmann, and a check-amalgamation target that verifies whether sources have been amalgamated, so the distributed header is a build artifact rather than a hand-maintained file. The core type is basic_json, a class template that the library instantiates for you as nlohmann::json. According to the README, each JSON object carries an overhead of one pointer (the maximal size of a union) and one enumeration element of one byte. The default generalization stores strings as std::string, numbers as int64_t, uint64_t or double, objects as std::map, arrays as std::vector, and Booleans as bool. That std::map choice is worth pausing on: it means object keys are ordered, and lookups are tree lookups rather than hash lookups. If you need different storage, the README notes you can template basic_json to your needs. The library also covers binary formats, listing BSON, CBOR, MessagePack, UBJSON and BJData alongside text JSON.

## Installing nlohmann/json and parsing a first document

The fastest install is no install at all: copy single_include/nlohmann/json.hpp into your include path. The README describes this as the whole code, with no adjustment of compiler flags or project settings required. If you prefer a package manager, the README states the library is included in all popular package managers, and the documentation site has a package managers page covering the integration paths.

For CMake projects, the repository ships a CMakeLists.txt and a cmake/ directory, so the header can be consumed as a CMake target rather than copied by hand. The README lists CMake, package managers and pkg-config as the three integration routes. The repository's CMakeLists.txt is the file to read for the exact target name your build should link against.

Once the header is reachable, the README's first example reads a JSON file and the second builds a json object from a JSON literal. The literal syntax is the part that surprises people coming from other C++ libraries: a trailing _json suffix turns a string literal into a parsed json value, as shown in the README's "Creating json objects from JSON literals" example. The README also shows serialization through dump and deserialization through get, plus STL-like access for iteration and indexing, and conversion from STL containers. What you should see when you run the file-reading example is a json value whose members you can index by key and print back out with dump.

## Where nlohmann/json is the wrong tool

The README says plainly that speed was not important to the authors and links to a parsing-time benchmark of faster libraries. If your program spends most of its time parsing large JSON documents, this is the wrong choice, and the project says so itself rather than hiding it. The same applies to memory: one pointer plus one byte per value, std::map for objects and std::vector for arrays is a reasonable default but not a compact representation, and on embedded targets with kilobytes of RAM that overhead compounds across a deep document. A second limitation is schema validation. The README lists JSON Pointer, JSON Patch and JSON Merge Patch among the examples, and the repository has no schema validator in its top-level entries; the README does not document schema validation, so if you need to check documents against a JSON Schema you will need a separate library. The third cost is compile time. A single header of this size included in many translation units is a known pattern for slow builds, and nothing in the README offers a mitigation beyond the forward-declaration header json_fwd.hpp, which exists precisely so that headers can name the type without pulling in the full definition.

## Alternatives and how their approach differs

The most instructive comparison is with RapidJSON, which the README's own benchmark link points toward as a faster option. RapidJSON is header-only as well, but it is built around a DOM of value types that you traverse explicitly, with an in-situ parsing mode that mutates the input buffer to avoid allocations. That is a different contract: you get speed and control, and you give up the operator-driven syntax that makes nlohmann/json read like a scripting language. If your code is a service that parses a few kilobytes of configuration at startup, the RapidJSON approach buys you nothing you can measure and costs you readability. If your code is a data pipeline parsing gigabytes, the nlohmann/json approach costs you real time. The second alternative worth naming is the standard library route: C++ has no JSON parser, so there is no std::json to fall back on, which is why a header-only third-party library is the common answer in the first place. Choose based on where the JSON sits in your hot path, not on which library has a nicer README.

## Maintenance, licence and the cost of upgrading

The MIT licence is the permissive default: it permits use, modification and redistribution provided the copyright notice and permission notice are retained. The repository keeps LICENSE.MIT at the top level alongside a LICENSES/ directory and a .reuse/ configuration, which indicates REUSE-compliant licence metadata rather than a bare licence file. That matters for organisations that audit licence headers per file. On maintenance, the last push to the develop branch was on 2025-04-11, which is the same date as the v3.12.0 release; the previous release, v3.11.3, was on 2023-11-28. That gap is the real upgrade consideration. This is not a project that ships monthly, so a bug fix you are waiting on may sit for a while, and the practical hedge is to pin a version rather than track develop. Because integration is a single header, upgrading is mechanical: replace json.hpp, or bump the version in your package manager, and rebuild. The risk is concentrated in the API surface you actually use, and the README's examples and the documentation site are the reference for whether a change touches you. The README does not document a rollback procedure, so keep the previous header or lockfile entry until your test suite passes against the new one.

## Conclusion

Adopt nlohmann/json when you want JSON in C++ with no build system changes: drop single_include/nlohmann/json.hpp into your tree or pull it through CMake, vcpkg, Conan or Meson, and you are done. Do not adopt it if your workload is dominated by parsing large documents under tight latency budgets, or if you need a validating schema engine, because the README lists speed and memory efficiency as explicit non-goals and the README does not document schema validation. Before committing, verify three things: that your compiler is on the supported list, that the version you pin is v3.12.0 or the release your package manager ships, and that your project can absorb the template compile-time cost of including the header in many translation units.

## FAQ

### How do I install nlohmann/json?

The README describes trivial integration: copy single_include/nlohmann/json.hpp into your project, with no library, subproject, dependencies or complex build system. The library is also included in all popular package managers, and the documentation site has a package managers page.

### How do I link the nlohmann/json package to my project?

The README lists CMake, package managers and Pkg-config as the integration routes, so the header is normally consumed as a CMake target rather than compiled separately. The repository's CMakeLists.txt is the file that defines the target name.

### How do I use nlohmann/json in C++?

Include nlohmann/json.hpp, alias nlohmann::json, then parse with json::parse and access values with operator[]. The README shows serialization through dump and deserialization through get, plus conversions to and from arbitrary types.

### How do I use #include nlohmann/json.hpp?

The README's examples include the header and then alias the type as nlohmann::json. The header is the amalgamated single_include/nlohmann/json.hpp file, so it must be on your include path.

### What is the fastest C++ JSON library?

The README does not claim nlohmann/json is the fastest. It states that speed was not a design goal, that there are certainly faster JSON libraries, and links to a parsing-time benchmark for comparison.

### How do I install nlohmann/json on Ubuntu?

The README states the library is included in all popular package managers and the documentation site has a package managers page; the README itself does not give an apt command. The alternative the README does describe is copying single_include/nlohmann/json.hpp into your project.

## Sources

- [Official documentation](https://json.nlohmann.me)
- [Official README](https://github.com/nlohmann/json#readme)
- [Project repository](https://github.com/nlohmann/json)
- [Release notes](https://github.com/nlohmann/json/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nlohmann-json