orjson

3.11.7 verified Tue May 12 auth: no python install: verified quickstart: verified

orjson is a fast and correct Python JSON library supporting dataclasses, datetimes, and numpy. The current version is 3.11.7, released on March 28, 2026, with a release cadence of approximately every 3 months.

pip install orjson

Common errors

error orjson.JSONEncodeError: Type is not JSON serializable: <class 'your_module.YourCustomObject'> ↓

cause orjson does not natively know how to serialize arbitrary Python objects or certain standard library types (like `Decimal`) without explicit instructions, resulting in a `JSONEncodeError` when such an object is encountered during serialization.

fix

Provide a default callable function to orjson.dumps() that converts unsupported types into a serializable format (e.g., a dictionary, string, or list). For Decimal objects, convert them to str or float.

error orjson.JSONDecodeError: str is not valid UTF-8: surrogates not allowed ↓

cause The input string or bytes provided to `orjson.loads()` contains invalid UTF-8 sequences or UTF-16 surrogates, which `orjson` strictly rejects as it adheres to strict JSON and UTF-8 conformance.

fix

Ensure that the input data is strictly valid UTF-8. If reading from a file, open it in binary mode ('rb') and pass the bytes directly to orjson.loads(). If decoding a string, verify its origin and encoding.

error TypeError: dumps() got an unexpected keyword argument 'indent' ↓

cause orjson.dumps() has a different API compared to Python's built-in `json.dumps()`. Many keyword arguments like `indent`, `separators`, or `sort_keys` are not directly supported and are instead controlled by bitwise `option` flags.

fix

Replace unsupported keyword arguments with their corresponding orjson.option flags. For example, use option=orjson.OPT_INDENT_2 for indentation and option=orjson.OPT_SORT_KEYS for sorting keys.

error TypeError: a bytes-like object is required, not 'str' ↓

cause This often occurs downstream when a function or framework expects a string type for JSON, but `orjson.dumps()` returns a `bytes` object (UTF-8 encoded JSON) by design, unlike the standard `json.dumps()` which returns a `str`.

fix

Explicitly decode the bytes output of orjson.dumps() to a str using .decode('utf-8') if a string is required by the consuming code. For example, orjson.dumps(data).decode('utf-8').

Warnings

breaking orjson 3.11.7 introduces a breaking change in the deserialization function, requiring explicit UTF-8 encoding for JSON input. ↓

fix Ensure that all JSON input passed to orjson.loads() is encoded in UTF-8.

gotcha Using orjson.dumps() on non-serializable objects will raise a TypeError. ↓

fix Ensure all objects passed to orjson.dumps() are serializable, or handle exceptions appropriately.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.04s 18.1M

3.10 slim (glibc) - - 0.03s 19M

3.11 alpine (musl) - - 0.07s 19.9M

3.11 slim (glibc) - - 0.05s 20M

3.12 alpine (musl) - - 0.04s 11.8M

3.12 slim (glibc) - - 0.06s 12M

3.13 alpine (musl) - - 0.04s 11.5M

3.13 slim (glibc) - - 0.04s 12M

3.9 alpine (musl) - - 0.04s 17.6M

3.9 slim (glibc) - - 0.04s 18M

Imports

orjson
```
import orjson
```
Ensure correct import path to avoid ImportError.

Quickstart verified last tested: 2026-04-23

A simple example demonstrating serialization and deserialization using orjson.

import orjson

# Serialize a Python object to JSON
data = {'name': 'Alice', 'age': 30}
json_bytes = orjson.dumps(data)
json_str = json_bytes.decode('utf-8')
print(json_str)

# Deserialize JSON to a Python object
json_bytes = b'{"name":"Alice","age":30}'
parsed_data = orjson.loads(json_bytes)
print(parsed_data)