rjson

Fast JSON for Python, written in Rust directly against the CPython C API. rjson is a drop-in replacement for orjson and the standard library json: orjson's exact output, json's errors and options, and less CPU for every request, log line and message you handle.

_{Geometric mean over the 10 cases of the reference benchmark, CPython 3.13.12, orjson 3.12.0, PGO wheels as published. NDJSON: 60–700-byte lines, CPython 3.11–3.13.}

Quick start

pip install pyrjson          # the PyPI name; you still `import rjson`

import rjson
from datetime import datetime
from uuid import uuid4

data = rjson.loads(b'{"name": "rjson", "tags": ["fast", "safe"]}')
payload = rjson.dumps({"at": datetime(2024, 5, 1, 9, 30), "id": uuid4(), **data})  # -> bytes
text = rjson.dumps_str(data)                  # -> str, without a .decode() copy
events = rjson.loads_ndjson(b'{"a": 1}\n{"a": 2}\n')   # -> [{'a': 1}, {'a': 2}]

Coming from orjson or json? Most code switches with a find-and-replace: migration guide.

Why rjson

• Faster where services spend time. Record-shaped data (API pages, DB rows, events) is where rjson leads most: loads of records is 1.40× faster than orjson, dumps 1.63×. Datetimes, UUIDs and Enums serialize 2.3–3.2× faster than orjson, with no default=.
• Drop-in, verified. dumps output is byte-identical to orjson's, including datetime, UUID, dataclasses and Enum. Errors are json.JSONDecodeError with json's positions. Every json.dumps option (indent, separators, sort_keys, ensure_ascii, allow_nan) has an exact equivalent, and lenient=True accepts exactly what json.loads accepts.
• More than a parser. loads_ndjson for NDJSON and JSON Lines, dumps_str for code that needs a str, and an rjson command line that replaces python -m json.tool (same output, 2–10× faster on real files).
• Hardened for untrusted input. Differential fuzzing against json, an AddressSanitizer CI job, nesting and thread-stack limits, and every CPython internal it uses gated by version and self-tested at import.
• Ready to install. PGO-optimized wheels for CPython 3.10–3.14 on Linux (glibc and musl, x86_64 and aarch64), macOS and Windows, with build provenance attestations. MIT licensed.

If rjson saves you CPU time, a ⭐ on GitHub helps other people find it.

rjson, orjson and json compared

What's new in 0.4.0

• Records parse up to 40% faster. A shape cache recognizes objects that repeat the same keys in the same order and builds each dict by copying a template, instead of inserting key by key. On CPython 3.11/3.12 those dicts also use about 16% less memory.
• rjson.loads_ndjson parses newline-delimited JSON in one call, 1.4–2.6× faster than a per-line loop on orjson, with loads's exact results and errors.
• rjson --json-lines uses it: --validate is 26% faster.

Full list: CHANGELOG.md.

Benchmarks

rjson is faster than orjson on 19 of the 20 loads/dumps cases. The other one is at parity within this host's run-to-run noise: int array dumps (0.99×; per-run 0.99–1.02×).

benches/fetch_corpus.sh                                   # sha256-pinned corpora -> benches/data/
scripts/build_pgo.sh python3.13 && pip install target/wheels/*cp313*.whl   # or a plain build
python benches/corpus_benchmark.py --json --repeat 11 --output-json results.json
python benches/make_charts.py results.json                # -> docs/img/*.svg + this table

NDJSON / JSON Lines

rjson ÷ orjson time (lower is better), each library's per-line loop vs rjson.loads_ndjson (plain release builds, best of 15):

Ranges span CPython 3.11, 3.12 and 3.13. Details: PERFORMANCE_REVIEW.md, loads item 13.

On production-shaped workloads

API responses and request bodies, log records, application types and str output, each checked for identical output before timing: docs/SHOWCASE.md (python benches/showcase.py). The examples below, measured end to end: Faster JSON in Python services.

Use it in your stack

FastAPI

from fastapi import FastAPI
from fastapi.responses import JSONResponse
import rjson

class RJSONResponse(JSONResponse):
    def render(self, content) -> bytes:
        return rjson.dumps(content)

app = FastAPI()

@app.get("/items")
def items() -> RJSONResponse:
    return RJSONResponse([{"id": 1, "name": "widget"}])

Return RJSONResponse(...) directly for dicts and lists. Measured on whole requests through the app, against stock FastAPI's own fast path (a return type, serialized by Pydantic's dump_json): a 50-row page is 1.25–1.4× faster, 1.8–1.9× with UUID/datetime/Enum fields, and a 1,000-row export 3.0–3.2× faster; against an endpoint without a return type, 9–74× (numbers). Don't set it as default_response_class: endpoints that return Pydantic models already go through dump_json. examples/fastapi_app.py adds a fallback for Decimal, Pydantic models and dataclasses, and rjson-parsed request bodies.

Django and Flask

# Django: a JsonResponse rendered by rjson
from django.http import HttpResponse, JsonResponse
import rjson

class RJSONResponse(JsonResponse):
    def __init__(self, data, safe=True, **kwargs):
        if safe and not isinstance(data, dict):
            raise TypeError("set safe=False to serialize non-dict objects")
        kwargs.setdefault("content_type", "application/json")
        HttpResponse.__init__(self, content=rjson.dumps(data), **kwargs)

# Flask: every jsonify() / dict return goes through rjson
from flask.json.provider import JSONProvider

class RJSONProvider(JSONProvider):
    def dumps(self, obj, **kwargs):
        return rjson.dumps_str(obj)

    def loads(self, s, **kwargs):
        return rjson.loads(s)

app.json = RJSONProvider(app)

examples/django_json.py and examples/flask_json.py add a fallback for Decimal, sets and dataclasses, and a request-body parser that turns invalid JSON into a 400 with the error position.

Logs, NDJSON, Redis and Kafka

records = rjson.loads_ndjson(body)                       # NDJSON in memory: one call
line = rjson.dumps(record) + b"\n"                        # one JSON object per log line
producer = KafkaProducer(value_serializer=rjson.dumps)    # bytes in, bytes out

• examples/json_logging.py: a logging.Formatter writing one JSON object per line (2.2–2.5 µs per record, 2.4–2.7× faster than the same formatter on json), plus streamed NDJSON read/write (writing 12.5× faster, reading 2.5–2.8×).
• examples/codec.py: a versioned bytes codec for Redis/Kafka with typed round trips, and value_serializer/value_deserializer callables. Round trips of JSON-native payloads are 4.1–4.6× faster than the same codec on json, and faster than pickle.
• docs/ASYNC.md: aiohttp, httpx, asyncpg, redis.asyncio and aiokafka one-liners, and how to keep large payloads from blocking the event loop.

Migrating from json or orjson

Two differences are by design: dumps raises on NaN/Infinity unless allow_nan=True (then NaN, as json writes it; orjson writes null), and floats below 1e-4 are written in shortest form (1e-7, as orjson; json writes 1e-07, the same value).

API

The wheel ships type stubs (py.typed), so mypy and pyright check calls to rjson.

Command line: JSON beautifier

pip install pyrjson also installs rjson, a faster drop-in for python -m json.tool: the same options and byte-for-byte the same output (checked against json.tool on the whole benchmark corpus), plus a formatter mode for files and CI.

$ curl -s https://api.github.com/repos/TinDang97/rjson | rjson --sort-keys --no-ensure-ascii
$ rjson data.json pretty.json            # beautify (indent 4, like json.tool)
$ rjson --compact data.json min.json     # minify (also --minify)
$ rjson --tab / --indent 2 / --no-indent # other layouts
$ rjson --json-lines --compact < events.jsonl   # JSON Lines / NDJSON, streamed
$ rjson -i --indent 2 config/*.json      # reformat files in place (only changed ones)
$ rjson --check --indent 2 config/*.json # CI: exit 1 if a file is invalid or not formatted
$ rjson --validate *.json                # exit 1 if a file is not valid JSON

End to end, process start included (CPython 3.13.12, median of 5; benches/cli_benchmark.py, results):

Syntax colors on a terminal (--color auto|always|never; honors NO_COLOR, FORCE_COLOR, PYTHON_COLORS), NaN/Infinity accepted like json.tool (--strict rejects them), errors as json.tool prints them (JSON Lines errors name the input line), atomic in-place writes that keep file permissions. Also python -m rjson, python -m rjson.tool, and rjson.tool.beautify(text, indent=4, ...) from Python. The only output difference from json.tool: floats below 1e-4 are written in shortest form (1e-7; json writes 1e-07, the same value). json.tool --json-lines FILE fails on CPython 3.13+ ("I/O operation on closed file"); rjson --json-lines FILE works.

Why it is faster than orjson

Both are Rust on the CPython C API with raw METH_FASTCALL entry points, a dict-key cache and zmij float formatting, so none of that explains the gap. These design choices do. Each row isolates one of them, is measured head to head with identical output (benches/why_faster.py, results; CPython 3.13, orjson 3.12.0, x86_64 with AVX-512, PGO wheel), and cites the orjson 3.12.0 source it describes.

The remaining difference is per-value work. rjson dispatches on exact type pointers, keeps the output cursor in a register, and sizes the output buffer from recent calls (orjson starts at 4 KiB and doubles, src/serialize/writer/byteswriter.rs). Instruction counts are deterministic, so host noise can't move them:

Where it is not different: page faults for large results are the same (the output has to be written either way), and indent=/sort_keys= are still slower than orjson's (a second pass over the compact output). Reproduce with python benches/why_faster.py (valgrind for the instruction counts). The full design, stage by stage: docs/ARCHITECTURE.md walks both pipelines function by function (input handling, the key and shape caches, number parsing, string decoding, the output-buffer policy, escaping kernels, the dict walk, native types, guarded mode and the safety checks), with the reason and the measured effect of each choice.

Production use

The full report, with every number and how it was measured: docs/PRODUCTION_READINESS.md. In short, rjson is ready for services whose payloads are JSON-native (dicts, lists, strings, numbers, datetimes, UUIDs), and not yet a drop-in for code that relies on orjson-only options.

Installation

The PyPI distribution is pyrjson (the name rjson on PyPI belongs to an unrelated project). You still import rjson.

pip install pyrjson        # or: uv add pyrjson

Wheels are PGO-optimized builds for CPython 3.10–3.14 on Linux (manylinux and musllinux, x86_64 and aarch64), macOS (arm64 and x86_64) and Windows (x86_64), with build provenance attestations (gh attestation verify <wheel> --repo TinDang97/rjson). Elsewhere pip builds from the sdist, which needs a Rust toolchain. The development version:

pip install "git+https://github.com/TinDang97/rjson"
# or, from a checkout:
pip install maturin && maturin develop --release

Compatibility

• CPython 3.10–3.14 on Linux x86_64/aarch64 (glibc and musl), macOS arm64 and Windows (CI). x86_64 builds target x86-64-v2 and select AVX2/AVX-512 kernels at runtime.
• Not supported: PyPy, GraalPy, free-threaded (no-GIL) builds, subinterpreters.

Status

Experimental. The API may change before 1.0; pin the version you test against.

Contributing

Bug reports and pull requests are welcome. CONTRIBUTING.md covers the development setup, the hard rules for code that touches the C API, and how to benchmark. Security issues: SECURITY.md. Changes: CHANGELOG.md.

uv venv .venv -p 3.13 && . .venv/bin/activate
uv pip install maturin orjson pytest
maturin develop --release && python -m pytest tests -q

Roadmap

• An incremental NDJSON decoder for sockets and a streaming encoder for async I/O; free-threading and subinterpreter support (docs/ASYNC.md)
• Performance: NEON kernels for aarch64; indent=/sort_keys= written by the serializer itself; deterministic PGO training (fixed iteration counts)

License

MIT © 2025 Tin Dang. src/lemire.rs is adapted from fast-float (MIT OR Apache-2.0).