nlohmann-json
JSON that behaves like a native C++ type — intuitive, header-only, widely adopted.
What it is
nlohmann-json is a modern C++ library for parsing, serializing, and manipulating JSON data. It provides an easy-to-use, STL-like interface and is header-only, making integration straightforward.
nlohmann-json allows creating JSON objects, parsing JSON strings, and serializing JSON data. It provides STL-like access, iterators, and convenient methods for manipulating nested data structures.
- Licence
- MIT
- Best known for
- `json j; j["key"] = value;` — it simply works the way you expect
When to use it
The question documentation cannot answer for you — because it cannot recommend something else.
Reach for it when
- Any C++ project needing JSON where developer ergonomics matter
- You want a single header you can drop in with no build changes
Look elsewhere when
- Parsing very large documents in a hot path — simdjson or RapidJSON are considerably faster
Installation
sudo apt install nlohmann-json3-devGetting started
The smallest useful thing you can do with it, and what each part means.
#include <nlohmann/json.hpp>
#include <iostream>
using json = nlohmann::json;
int main() {
json j;
j["name"] = "Alice";
j["age"] = 30;
std::cout << j["name"] << " is " << j["age"] << " years old." << std::endl;
return 0;
}#include <nlohmann/json.hpp>
#include <iostream>
#include <string>
using json = nlohmann::json;
int main() {
std::string s = R"({"city":"NYC","population":8419000})";
json j = json::parse(s);
std::cout << j["city"] << std::endl;
return 0;
}Advanced usage
Where the library earns its place over a simpler alternative.
#include <nlohmann/json.hpp>
#include <iostream>
using json = nlohmann::json;
int main() {
json j = { {"name", "Alice"}, {"age", 30} };
for (auto& [key, value] : j.items()) {
std::cout << key << ": " << value << std::endl;
}
return 0;
}#include <nlohmann/json.hpp>
#include <iostream>
using json = nlohmann::json;
int main() {
json j = { {"name", "Bob"}, {"active", true} };
std::string s = j.dump(4); // pretty print with 4 spaces
std::cout << s << std::endl;
return 0;
}#include <nlohmann/json.hpp>
#include <iostream>
using json = nlohmann::json;
int main() {
json j = {"apple", "banana", "cherry"};
j.push_back("date");
for (auto& fruit : j) std::cout << fruit << std::endl;
return 0;
}Errors and fixes
The failures you are most likely to hit, and what actually resolves them.
- nlohmann::json::parse_error
- Occurs when parsing invalid JSON. Validate JSON format or wrap in try-catch.
- nlohmann::json::type_error
- Occurs when accessing a value with an incompatible type. Check JSON data types before access.
Best practices
- Prefer `json::parse` with try-catch blocks to handle malformed input.
- Use `dump()` with indentation for human-readable JSON output.
- Leverage STL-like iterators for manipulation of objects and arrays.
- Validate JSON structure before accessing deeply nested fields.
- Keep library updated to benefit from new C++ standard support and bug fixes.
Alternatives
Comparable options, and the reason you would pick one over the other.
simdjson
Gigabytes per second parsing; a lower-level API in exchange
RapidJSON
Faster and lighter, with a more verbose DOM/SAX interface
Background
Why it exists, and what it was reacting to.
nlohmann-json was created by Niels Lohmann in 2013 to offer a simple, intuitive, and type-safe way to handle JSON in C++. It quickly became popular due to its ease of use, compatibility with modern C++ standards, and rich feature set.