orjson

library3.12.0pypypi✓ verified 24d ago

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.

serialization data

pip install orjson

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · ORJSON

orjson

serializationpythonv3.12.0

Install

2.2s avg

Import

46ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.12.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.048s · 18.1MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.2s · import 0.044s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

orjson

✓ import orjson

Ensure correct import path to avoid ImportError.

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)

Debug

Known issues

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

affects: 3.11.7

gotchaUsing orjson.dumps() on non-serializable objects will raise a TypeError.

fix

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

affects: all

Errors

Common errors & fixes

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

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

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

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.

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

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.

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

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')`.

Upgrade

Version history

3.12.0latest on PyPI · released Aug 14, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/ijl/orjson ↗

packagehttps://pypi.org/project/orjson/ ↗

docshttps://github.com/ijl/orjson ↗

changeloghttps://github.com/ijl/orjson/blob/master/CHANGELOG.md ↗