Skip to content
Get packs

Guide · Open source

How to use nlohmann/json in C++: install and handle JSON

Updated · written with AI from the project's own documentation and checked against our catalogue data

nlohmann/json, titled JSON for Modern C++, is an MIT-licensed C++ library that lets your program read and write JSON using familiar C++ containers and operators. This guide explains how it is distributed, what you need to get started, and which features the project's README describes. By the end you will know whether it suits your project and how to set it up.

JSON for Modern C++nlohmann/json · ★ 50.8k · MIT

Quick start

  1. 1Confirm your compiler. Make sure your compiler supports C++11 or later, as the README requires.
  2. 2Clone the repository. Run git clone https://github.com/nlohmann/json.git to get the source.
  3. 3Find the single header. Open single_include/nlohmann/json.hpp in the cloned folder, which is the library's one header file.
  4. 4Add the header to your project. Place json.hpp where your compiler can find it, so your code can include it.
  5. 5Read the examples. Work through the README's example topics, such as reading from a file and creating objects from literals.
  6. 6Try JSON Pointer or Patch if needed. If your project needs them, read the JSON Pointer and JSON Patch sections of the README.

What nlohmann/json is and how it works

The library lets you work with JSON data much like std::map and std::vector. JSON objects and arrays are handled with C++ operators, so code that reads like ordinary C++ can access JSON content.

The README says the default data types are std::string for strings, int64_t, uint64_t or double for numbers, std::map for objects, std::vector for arrays and bool for Booleans. The generalized class basic_json can be templated to suit your needs.

  • Language: C++ only
  • Licence: MIT
  • Distribution: a single header file named json.hpp
  • Also mentioned in the README: CBOR, MessagePack, BSON, JSON Pointer and JSON Patch

Check the requirements before you install

The README lists a C++11 or later compiler as the prerequisite. The project states that the library has no dependencies and no subproject, and that it is written in vanilla C++11.

The README says that, in its design, everything should require no adjustment of your compiler flags or project settings. It also says the library is included in popular package managers, but the excerpt does not list which ones.

  • Compiler: C++11 or later
  • Dependencies: none, according to the README
  • Build system: no complex build system is required, according to the README

Install nlohmann/json by cloning the repository

The install method is clone-and-build. The README excerpt gives one command to get the source, which clones the repository from GitHub.

The main header is single_include/nlohmann/json.hpp in the repository. Copy it into your project or point your build at it. The README excerpt does not show the build steps beyond cloning, so check the documentation at json.nlohmann.me for further setup details.

  • Clone the repository from the URL below
  • Locate single_include/nlohmann/json.hpp in the cloned folder
  • Add that header to your project's include path
git clone https://github.com/nlohmann/json.git

Know what the README's examples cover

The README lists example topics you can read through to learn the API. The excerpt does not include the example code itself, so open the README or the code examples folder in the repository to see it.

The examples cover reading JSON from a file, creating json objects from JSON literals, serialization and deserialization, STL-like access, conversion from STL containers, JSON Pointer and JSON Patch, JSON Merge Patch, implicit conversions, conversions to and from arbitrary types and specializing enum conversion.

  • Read JSON from a file
  • Creating json objects from JSON literals
  • Serialization and deserialization
  • STL-like access
  • JSON Pointer and JSON Patch
  • JSON Merge Patch
  • Conversions to and from arbitrary types

Choose the right library for your project

The README says the library was designed for ease of use and quick integration. It says faster JSON libraries exist, so raw parsing speed is not its focus.

The README names RapidJSON, simdjson, Boost.JSON and PicoJSON as comparable projects. Consider these if parsing speed is your main need. The excerpt does not compare build times, so test compile cost in your own project if it matters.

  • Good fit: C++ apps that need to read or write JSON with little setup
  • Good fit: teams that want a header-only style setup with no dependencies
  • Less suited: projects that need the fastest possible parsing
  • Less suited: non-C++ projects, since the library is for C++ only

What people use it for

  • Reading configuration or data files in a C++ application
  • Creating JSON objects from literals in code and serializing them
  • Applying JSON Patch or JSON Pointer operations to JSON data in C++
  • Converting between JSON and C++ types, including user-defined types

Frequently asked questions

Is nlohmann json free to use?

Yes. The README gives the licence as MIT, and the repository includes a LICENSE.MIT file. Check that file for the exact terms before you use the library in a commercial product.

What do I need to install nlohmann json?

You need a C++11 or later compiler. The README's install method is clone-and-build, and the main step is cloning the repository and adding the single header json.hpp to your project.

Does nlohmann json have dependencies?

The README says the library has no dependencies and no complex build system. It is distributed as one header file, which is the reason the project describes it as simple to add.

Is nlohmann json faster than other JSON libraries?

No. The README says there are certainly faster JSON libraries. It says the library is aimed at speeding up development with a single header, so choose a faster library if raw parsing speed is your main need.

What are the alternatives to nlohmann json?

The README names RapidJSON, simdjson, Boost.JSON and PicoJSON as comparable projects. Compare them on the features and performance your project needs.

Can I use nlohmann json with languages other than C++?

No. The README says the library is for C++ only, so use a library in your project's own language if you are not working in C++.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

nlohmann/json suits C++ developers who want to read or write JSON with familiar containers, a single header and no dependencies, and it supports JSON Pointer and JSON Patch. Pick a different library, such as simdjson or RapidJSON, if your main need is the fastest possible parsing, or if you do not work in C++.

Install options & downloads