Guide · Open source
How to use cJSON: copy or build the C JSON library
Updated · written with AI from the project's own documentation and checked against our catalogue data
cJSON is an open-source C library for reading and writing JSON data, released under the MIT licence. This guide is for C developers who need to add JSON handling to a program, especially small or embedded projects. By the end you will know the two main ways to add cJSON to a project, how to include it in your code, how its data structure works, and what to check before relying on it.
cJSONDaveGamble/cJSON · ★ 13.1k · MIT Install options & downloads Quick start
- 1Choose how to add cJSON. Copy cJSON.c and cJSON.h into your project for the simplest setup, or build with CMake if you want the full feature set.
- 2Build with CMake. Create a build directory, run cmake .. inside it, then run make to compile the library.
- 3Install system-wide (optional). Run make install to place the headers in /usr/local/include/cjson and the libraries in /usr/local/lib by default.
- 4Include the header. Add #include <cjson/cJSON.h> to the C files that need JSON handling.
- 5Read the caveats. Check the README's Caveats section on thread safety, floating point and deep nesting before using cJSON in production code.
What cJSON is and when it fits
cJSON is a C library for reading and writing JSON. The README describes it as an ultralightweight JSON parser in ANSI C, and says its goal is to be the dumbest possible parser you can get your job done with.
It is a good fit when you write in C and want a tiny dependency, or when you want to copy one .c file and one .h file into your project instead of managing a build dependency. It is not a ready-made application; it is code you include in your own program.
- Use it for C programs that read or write JSON.
- Use it for embedded or small projects where a tiny dependency is preferred.
- Skip it if you are not writing in C, since the README does not cover other language bindings.
Option 1: copy the source into your project
Because the entire library is one C file and one header file, you can copy cJSON.h and cJSON.c into your project's source and start using it. This avoids any build dependency.
The README notes that cJSON is written in ANSI C (C89) so it can support as many platforms and compilers as possible.
Option 2: build and install with CMake
CMake is the recommended build method and gives you the most features. The README recommends an out-of-tree build, meaning the compiled files go in a separate build directory. On a Unix platform, create a build directory and run CMake inside it, then compile with make.
To install the library system-wide, run make install. By default the headers go to /usr/local/include/cjson and the libraries go to /usr/local/lib. The install also includes pkg-config files and CMake config files so other CMake projects can find the library.
CMake options are passed with -D flags. Some useful ones from the README are listed below; for example, -DENABLE_CJSON_UTILS=On builds cJSON_Utils (off by default) and -DBUILD_SHARED_LIBS=On builds shared libraries (on by default).
- -DENABLE_CJSON_TEST=On: build the tests (on by default).
- -DENABLE_CJSON_UTILS=On: build cJSON_Utils (off by default).
- -DBUILD_SHARED_LIBS=On: build the shared libraries (on by default).
- -DBUILD_SHARED_AND_STATIC_LIBS=On: build both shared and static libraries (off by default).
- -DCMAKE_INSTALL_PREFIX=/usr: set a prefix for the installation.
- -DENABLE_SANITIZERS=On: compile with AddressSanitizer and UndefinedBehaviorSanitizer (off by default).
mkdir build
cd build
cmake ..
make
make installOther build options: Makefile, Meson and vcpkg
If you do not have CMake but have GNU make, the README describes a makefile. Be aware that it is marked as deprecated, with only bug fixes planned, so CMake is preferred where possible. Running make all builds static and shared libraries plus a small test program, not the full test suite.
For Meson, the README shows a project that declares a libcjson dependency and links an executable against it. cJSON can also be installed with the vcpkg dependency manager using the vcpkg install cjson command shown in the README.
make allInclude cJSON in your C code
If you installed cJSON with CMake or the Makefile, include the header like this. The README's include path assumes the installed layout.
#include <cjson/cJSON.h>Understand the cJSON data structure
cJSON represents JSON data with the cJSON struct. Each item represents one JSON value and links to others through next, prev and child pointers. Its string field holds the name of an object member, and valuestring holds string values.
The type field is stored as a bit-flag, so you cannot find an item's type by comparing the value of type directly. Instead, use the matching cJSON_Is... function, which performs a NULL check before testing the type.
Writing to valueint is deprecated; use cJSON_SetNumberValue instead.
typedef struct cJSON
{
struct cJSON *next;
struct cJSON *prev;
struct cJSON *child;
int type;
char *valuestring;
int valueint;
double valuedouble;
char *string;
} cJSON;Check the caveats before relying on cJSON
The README has a Caveats section that covers limits you should check if your project needs strong guarantees on edge cases. The topics it lists are zero characters, character encoding, the C standard, floating point numbers, deep nesting of arrays and objects, thread safety, case sensitivity and duplicate object members.
If your project depends on any of these, read the matching caveat in the README and test it in your own code.
- Zero Character
- Character Encoding
- C Standard
- Floating Point Numbers
- Deep Nesting Of Arrays And Objects
- Thread Safety
- Case Sensitivity
- Duplicate Object Members
What people use it for
- Reading JSON configuration or data files inside a C program.
- Writing JSON output from an embedded device or small tool.
- Adding JSON handling to a C project without managing an external build dependency by copying two files.
Frequently asked questions
Is cJSON free to use?
cJSON is released under the MIT licence. The licence permits use, copying, modification, merging, publishing, distribution, sublicensing and sale, provided the copyright notice is included. The software is provided as-is with no warranty.
How do I install cJSON?
You can copy cJSON.c and cJSON.h into your project, or build it with CMake using mkdir build, cd build, cmake .. and make. Running make install then places the headers and libraries in system folders by default.
Does cJSON work with languages other than C?
cJSON is a C library, and the README does not cover other language bindings. If you work in another language, you would need to look for a library made for that language.
What are the alternatives to cJSON?
The README lists jansson, Parson, json-c and RapidJSON as comparable projects. Choose based on whether you need a single-file copy, a C or C++ API, and the edge case behaviour described in each project.
Is cJSON thread safe?
The README has a Thread Safety entry in its Caveats section, so it is not something to assume. Read that section and test your own multi-threaded use before relying on it.
Why is cJSON recommended for small or embedded projects?
The README describes cJSON as an ultralightweight parser that is a single C file and a single header, which makes it easy to copy into a project. It is written in ANSI C to work across many platforms and compilers.
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
Use cJSON if you write C, want a tiny dependency or a copy-in-two-files setup, and prefer a simple parser with little abstraction. Pick a different library if you use another language, need a ready-made application, or need firm guarantees on edge cases without testing them first.
Install options & downloads