simdjson

Software

The library is part of major linux distributions like Ubuntu, Debian, Arch Linux, Fedora, Alpine and as a FreeBSD package. It is in Microsoft vcpkg. It is available as an MSYS2 package, from brew and from conan. We publish it as single-header library as well as a CMake build from the GitHub repository. We have a simdjson organization on GitHub.

Quick Start

Prerequisites: a recent C++ compiler.

  1. Pull simdjson.h and simdjson.cpp from our singleheader directory into a directory of your choice, along with the sample file twitter.json from our jsonexamples repository.
SIMDJSON_BASE="https://raw.githubusercontent.com/simdjson/simdjson/master/"

wget "${SIMDJSON_BASE}singleheader/simdjson.h" \
     "${SIMDJSON_BASE}singleheader/simdjson.cpp" \
     "${SIMDJSON_BASE}jsonexamples/twitter.json"
  1. Create quickstart.cpp:
   #include "simdjson.h"
   using namespace simdjson;
   int main(void) {
      ondemand::parser parser;
      padded_string json = padded_string::load("twitter.json");
      ondemand::document tweets = parser.iterate(json);
      std::cout << uint64_t(tweets["search_metadata"]["count"]) 
        << " results." << std::endl;
   }

  1. Compile: 

       c++ -o quickstart quickstart.cpp simdjson.cpp -std=c++17

  2. Run: 

       ./quickstart

Quick Start in Python

Prerequisites: Python 3.10 or newer. Our official Python binding, fastsimdjson, has wheels for Linux, macOS and Windows, including free-threaded Python 3.14 and 3.15.

  1. Install it, and download the sample file twitter.json:
pip install fastsimdjson     # or: uv pip install fastsimdjson
wget https://raw.githubusercontent.com/simdjson/simdjson/master/jsonexamples/twitter.json
  1. Use it as a drop-in replacement for the json module. loads, load, dumps and dump return the same values and strings as their json counterparts:
import fastsimdjson

doc = fastsimdjson.loads(b'{"a": [1, 2.5, "x", true, null]}')
# {'a': [1, 2.5, 'x', True, None]}
fastsimdjson.dumps(doc)              # '{"a": [1, 2.5, "x", true, null]}'
fastsimdjson.dumpb(doc)              # b'{"a":[1,2.5,"x",true,null]}', like orjson.dumps
  1. When you need only part of a document, parse returns lazy views that convert values only when you access them:
doc = fastsimdjson.parse_file("twitter.json")
print(doc["search_metadata"]["count"], "results.")
names = [s["user"]["screen_name"] for s in doc["statuses"]]
doc.at_pointer("/statuses/0/user/name")   # JSON Pointer (RFC 6901)
  1. Read streams of documents (NDJSON, JSON Lines). With free-threaded Python, threads=N parses on many threads; fields= extracts only the values you need:
data = open("log.ndjson", "rb").read()
for record in fastsimdjson.loads_many(data):
    ...
docs = fastsimdjson.loads_many(data, threads=16)        # a list, in order
pairs = fastsimdjson.loads_many(data, fields=["/type", "/payload/action"])
  1. Convert NDJSON to Apache Arrow tables and back, for pyarrow, polars or DuckDB, on many threads:
import pyarrow as pa
table = pa.table(fastsimdjson.loads_arrow(data))         # schema inferred
data = fastsimdjson.dumpb_arrow(table, threads=8)        # NDJSON bytes
  1. Convert JSON to MessagePack and back, without building Python objects:
packed = fastsimdjson.json_to_msgpack(b'{"id": 1, "tags": ["a", "b"]}')
fastsimdjson.msgpack_to_json(packed)     # b'{"id":1,"tags":["a","b"]}'

See the fastsimdjson README for the full API.

Documentation

Usage documentation is available:

  • Basics is an overview of how to use simdjson and its APIs.
  • Builder is an overview of how to efficiently write JSON strings using simdjson.
  • Performance shows some more advanced scenarios and how to tune for them.
  • Implementation Selection Selection describes runtime CPU detection and how you can work with it.

Real-world usage

If you are planning to use simdjson in a product, please work from one of our releases.

Official companion libraries

The simdjson organization publishes libraries built on simdjson:

  • fastsimdjson: our official Python binding (pip install fastsimdjson). A drop-in replacement for the json module’s loads, load, dumps and dump, over 3 times faster than the standard library. It also offers lazy parsing, multithreaded NDJSON with free-threaded Python, and conversion to Apache Arrow and MessagePack. Available on PyPI.
  • simdjson_arrow: reads newline-delimited JSON into Apache Arrow record batches, and writes Arrow record batches as JSON, on one thread or many. Several times faster than Arrow C++’s own JSON reader.
  • simdjson_msgpack: converts JSON to MessagePack and back, one document or many, on many threads.

Bindings and Ports of simdjson

We distinguish between “bindings” (which just wrap the C++ code) and a port to another programming language (which reimplements everything).