rjson

Fast JSON for Python, written in Rust directly against the CPython C API. A faster alternative to orjson and the standard library json for web APIs (FastAPI, Django, Flask), logging and NDJSON, caches and message queues; switching is mostly a find-and-replace (migration guide).

• Faster than orjson on 18 of the 20 cases of the reference benchmark (geomean loads 1.17×, dumps 1.36×) and on 21 of 22 production-shaped workloads (1.52×); 3.5× / 14× faster than json.
• Same output as orjson, byte for byte, including datetime, UUID, dataclasses and Enum; dumps_str returns a str directly.
• Hardened for untrusted input: differential fuzzing against json, an AddressSanitizer CI build, and stack checks for deeply nested documents.
• A JSON beautifier on the command line: rjson is a drop-in python -m json.tool (same output) that is 2–10× faster on real files, with in-place formatting and a CI --check (command line).
• CPython 3.10–3.14 wheels for Linux (glibc and musl), macOS and Windows. MIT licensed.

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

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

On production-shaped workloads

Identical output is checked before timing. FastAPI, logging, NDJSON and Redis/Kafka numbers for the examples: Faster JSON in Python services. Numbers, method and the one slower case: docs/SHOWCASE.md (python benches/showcase.py).

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

Usage

from datetime import datetime
from decimal import Decimal
from uuid import uuid4

import rjson

data = rjson.loads('{"name": "rjson", "tags": ["fast", "safe"], "stars": 1e3}')
payload = rjson.dumps(data)        # b'{"name":"rjson","tags":["fast","safe"],"stars":1000.0}'
text = rjson.dumps_str(data)       # the same JSON as a str

rjson.dumps({"at": datetime(2024, 5, 1, 9, 30), "id": uuid4()})  # datetime, UUID, dataclass, Enum: native
rjson.dumps({"price": Decimal("9.99")}, default=str)             # convert the rest with default=

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

• lenient=True (loads): accepts everything json.loads accepts, with the same result: NaN/Infinity/-Infinity, a UTF-8 BOM on bytes and numbers overflowing to inf are parsed natively (no speed cost); lone surrogates ("\ud83d", sent by JavaScript clients that cut an emoji in half), UTF-16/UTF-32 bytes and nesting deeper than 1024 go through json.loads. The default stays strict, like orjson.
• Types: dict (str keys), list, tuple, str, int (any size), float, bool, None, and their subclasses (IntEnum, str enums, OrderedDict, namedtuple, …).
• Native types, byte-identical to orjson: datetime (RFC 3339: 2024-05-01T09:30:00, .ffffff only when non-zero, +HH:MM when aware), date, time, uuid.UUID (lowercase, hyphenated), dataclasses (as objects; _-prefixed names skipped, as in orjson) and Enum members (their value). Subclasses of datetime/date/time/UUID go to default=. Three orjson bugs are not copied: a tzinfo whose utcoffset() raises, or a deleted __slots__ field, raise the Python error (orjson crashes); utcoffset() returning None gives no offset, as in isoformat() (orjson writes +00:00); an offset whose seconds round up to a whole hour carries into the hour (orjson writes +00:60).
• passthrough=: rjson.PASSTHROUGH_* flags send those kinds to default= (or make them raise) instead, e.g. to tag them for an exact round trip (examples/codec.py), like orjson's OPT_PASSTHROUGH_*.
• non_str_keys=True: dict keys may be int (any size), float, bool, None (written exactly as json.dumps writes them: "1", "1e-07", "NaN", "true", "null"), Enum members (their value), and datetime/date/time/UUID (their native text, like orjson's OPT_NON_STR_KEYS). Other key types raise; default= is not called for keys. Like json and orjson, a coerced key can duplicate a str key ({1: …, "1": …} writes "1" twice). Off by default: a non-str key raises.
• indent= / sort_keys=: indent=2 and sort_keys=True give exactly the bytes of orjson's OPT_INDENT_2 and OPT_SORT_KEYS (keys sorted by code point; dataclass fields keep their order); other widths (indent=4, indent=0) lay out like json.dumps(indent=n). Compact calls pay nothing for them; the options themselves are not yet as fast as orjson's (twitter.json: sort_keys 0.78×, indent=2 0.48×).
• json.dumps options: indent also takes a str (indent="\t"), and separators=, ensure_ascii=True (non-ASCII and DEL as \uXXXX, surrogate pairs above U+FFFF) and allow_nan=True (NaN/Infinity/-Infinity) behave as in json.dumps, so any json.dumps call has an exact equivalent (numbers aside, see floats below 1e-4). Only the defaults differ: compact, non-ASCII kept, NaN raises. With ensure_ascii=True, dumps also writes lone surrogates (as \udXXX, like json).
• default=: called with each value rjson cannot serialize; its return value is serialized in its place (and passed to default again if still unsupported), as in json.dumps and orjson. Exceptions it raises propagate unchanged. It is not called for NaN/Infinity or dict keys (see non_str_keys=), which still raise. Supported values never reach it, so native data runs at full speed.
• Errors: loads raises JSONDecodeError with pos/lineno/colno matching json. dumps/dumps_str raise JSONEncodeError for unsupported types, non-str keys (unless non_str_keys=True), NaN/Infinity, and nesting deeper than 254 (which also catches circular references), so both except TypeError and except ValueError catch it. A lone surrogate raises UnicodeEncodeError in dumps; dumps_str passes it through.
• Precision: floats round-trip exactly (shortest representation, e.g. 1e+16), and integers of any size are exact in both directions. loads accepts nesting up to 1024.

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

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 and python -m rjson.tool, and rjson.tool.beautify(text, indent=4, ...) from Python.

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

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.

Migrating from json or orjson

Most code migrates with a find-and-replace:

What does not carry over yet, and how to handle it:

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.

Logging, NDJSON, Redis and Kafka

• 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 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.

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), and not yet a drop-in for code that relies on orjson's options.

Compatibility

• CPython 3.10–3.14 on Linux x86_64/aarch64, 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.

Why it is faster than orjson

Both are Rust on the CPython C API, cache dict keys and format floats with zmij. Internals rjson relies on are version-gated and self-tested at import (CLAUDE.md); details in docs/PERFORMANCE_REVIEW.md.

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

• Streaming decoder/encoder for async I/O; free-threading and subinterpreter support (docs/ASYNC.md)
• Performance: NEON kernels for aarch64

License

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