orjson Documentation

orjson is a high-performance, correct JSON library for Python. It is designed to be significantly faster than the standard json library, with orjson.dumps() performing approximately 10x faster and orjson.loads() performing approximately 2x faster.

Key features include:

• Native serialization of dataclass, datetime, numpy, and UUID instances.
• Strict compliance with UTF-8 and RFC 8259.
• Support for CPython 3.10 through 3.15.
• Support for various architectures including x86_64 (with AVX-512 optimization), ARM64, and more.

Note: orjson does not provide built-in utilities for reading from or writing to files; it operates on bytes/strings.

To install the orjson package from PyPI, add it to your dependency configuration.

For requirements.in or requirements.txt:

orjson >= 3.10,<4

For pyproject.toml:

orjson = "^3.10"

To package orjson, you need Rust 1.95 or higher, a C compiler, and the maturin build tool. It is recommended to use the --release and --strip flags for optimal performance and smaller binaries. Note that using a Rust nightly channel can provide significant performance benefits, though it may introduce breaking changes.

maturin build --release --strip

The orjson tests are included in the PyPI source distribution and require pytest. Some tests use optional dependencies like pytz and numpy (listed in test/requirements.txt); if these are missing, those specific tests will be skipped. To run the tests quietly, use:

pytest -q test

orjson serializes datetime.datetime objects to RFC 3339 format (compatible with isoformat()).

Supported Timezones: zoneinfo (recommended for speed), datetime.timezone.utc, pendulum, pytz, or dateutil/arrow.

Constraints & Options:

• datetime.time objects must not have a tzinfo.
• datetime.date objects always serialize.
• Use orjson.OPT_PASSTHROUGH_DATETIME to disable datetime serialization.
• Use orjson.OPT_UTC_Z to use the "Z" suffix for UTC instead of "+00:00".
• Use orjson.OPT_NAIVE_UTC to treat datetimes without timezone info as UTC.

>>> import orjson, datetime, zoneinfo
>>> orjson.dumps(
    datetime.datetime(2018, 12, 1, 2, 3, 4, 9, tzinfo=zoneinfo.ZoneInfo("Australia/Adelaide"))
)
b'"2018-12-01T02:03:04.000009+10:30"'

If orjson.dumps() encounters a type it cannot serialize, it raises a JSONEncodeError. You can provide a default callable (function, lambda, or class instance) to handle these types. The callable should return a supported type or raise a TypeError if the type cannot be handled.

import orjson, decimal

def default(obj):
    if isinstance(obj, decimal.Decimal):
        return str(obj)
    raise TypeError

# Usage
json_bytes = orjson.dumps(decimal.Decimal("0.0842389659712649442845"), default=default)

orjson serializes dataclasses.dataclass instances natively, providing significant performance benefits (40-50x faster than using json with dataclasses.asdict()). It supports all variants, including those using __slots__, frozen dataclasses, and subclasses. Dataclasses are serialized as maps, with attributes appearing in the order defined in the class.

>>> import dataclasses, orjson, typing

@dataclasses.dataclass
class Member:
    id: int
    active: bool = dataclasses.field(default=False)

@dataclasses.dataclass
class Object:
    id: int
    name: str
    members: typing.List[Member]

>>> orjson.dumps(Object(1, "a", [Member(1, True), Member(2)]))
b'{"id":1,"name":"a","members":[{"id":1,"active":true},{"id":2,"active":false}]}'

orjson serializes uuid.UUID instances to RFC 4122 format.

>>> import orjson, uuid
>>> orjson.dumps(uuid.uuid5(uuid.NAMESPACE_DNS, "python.org"))
b'"886313e1-3b8a-5372-9b90-0c9aee199e5d"'

orjson provides high-performance native serialization for numpy.ndarray and various numpy scalar types.

Requirements:

• You must pass option=orjson.OPT_SERIALIZE_NUMPY to orjson.dumps().
• The array must be a contiguous C array (C_CONTIGUOUS).
• The array must be in the native endianness of the system.

Note: If the array is not contiguous or contains unsupported types, orjson falls back to the default handler. You can use obj.tolist() within your default function to handle these cases.

>>> import orjson, numpy
>>> orjson.dumps(
        numpy.array([[1, 2, 3], [4, 5, 6]]),
        option=orjson.OPT_SERIALIZE_NUMPY,
    )
b'[[1,2,3],[4,5,6]]'

orjson supports 64-bit integers (signed min to unsigned max). To ensure compatibility with environments that only support 53-bit integers (like web browsers), use the orjson.OPT_STRICT_INTEGER option. This will cause orjson.dumps() to raise a JSONEncodeError if a value exceeds the 53-bit range.

>>> import orjson
>>> orjson.dumps(9007199254740992, option=orjson.OPT_STRICT_INTEGER)
JSONEncodeError: Integer exceeds 53-bit range

orjson serializes enum.Enum members natively. For enums containing unsupported types, provide a default function to orjson.dumps() to handle the conversion.

>>> import enum, datetime, orjson
>>> 
class DatetimeEnum(enum.Enum):
    EPOCH = datetime.datetime(1970, 1, 1, 0, 0, 0)
>>> orjson.dumps(DatetimeEnum.EPOCH)
b'"1970-01-01T00:00:00"'