0
# orjson
1

2
orjson is a fast, correct JSON library for Python. It benchmarks as the fastest Python library for JSON and is more correct than the standard json library or other third-party libraries. It serializes dataclass, datetime, numpy, and UUID instances natively with significant performance benefits over standard library alternatives.
3

4
## Package Information
5

6
- **Package Name**: orjson  
7
- **Package Type**: pypi
8
- **Language**: Python (with Rust backend)
9
- **Installation**: `pip install orjson`
10
- **Version**: 3.11.3
11
- **Python Support**: CPython 3.9, 3.10, 3.11, 3.12, 3.13, 3.14
12

13
## Core Imports
14

15
```python
16
import orjson
17
```
18

19
Or import specific components:
20

21
```python
22
from orjson import dumps, loads, Fragment, JSONDecodeError, JSONEncodeError
23
from orjson import OPT_INDENT_2, OPT_SORT_KEYS, OPT_SERIALIZE_NUMPY
24
```
25

26
## Basic Usage
27

28
```python
29
import orjson
30
import datetime
31
import numpy
32

33
# Basic serialization and deserialization
34
data = {"type": "job", "id": 123, "active": True}
35
json_bytes = orjson.dumps(data)
36
parsed_data = orjson.loads(json_bytes)
37

38
# Advanced usage with options and native type support
39
complex_data = {
40
    "created_at": datetime.datetime(1970, 1, 1),
41
    "status": "🆗",
42
    "payload": numpy.array([[1, 2], [3, 4]]),
43
}
44

45
# Serialize with options
46
json_bytes = orjson.dumps(
47
    complex_data, 
48
    option=orjson.OPT_NAIVE_UTC | orjson.OPT_SERIALIZE_NUMPY | orjson.OPT_INDENT_2
49
)
50

51
# Parse back to Python objects
52
result = orjson.loads(json_bytes)
53
```
54

55
## Capabilities
56

57
### JSON Serialization
58

59
Converts Python objects to JSON bytes with high performance and native support for many Python types.
60

61
```python { .api }
62
def dumps(
63
    __obj: Any,
64
    default: Callable[[Any], Any] | None = None,
65
    option: int | None = None,
66
) -> bytes:
67
    """
68
    Serialize Python objects to JSON bytes.
69
    
70
    Args:
71
        __obj: Object to serialize (positional only)
72
        default: Optional callable to handle unsupported types
73
        option: Optional serialization options (bitwise OR of OPT_* constants)
74
    
75
    Returns:
76
        JSON as UTF-8 encoded bytes
77
        
78
    Raises:
79
        JSONEncodeError: On serialization failures
80
    """
81
```
82

83
**Native type support**: `str`, `dict`, `list`, `tuple`, `int`, `float`, `bool`, `None`, `dataclasses.dataclass`, `typing.TypedDict`, `datetime.datetime`, `datetime.date`, `datetime.time`, `uuid.UUID`, `numpy.ndarray` (with `OPT_SERIALIZE_NUMPY`), `enum.Enum`, and subclasses of `str`, `int`, `dict`, `list`, `dataclass`.
84

85
**Usage example with default handler**:
86

87
```python
88
import orjson
89
import decimal
90

91
def default_handler(obj):
92
    if isinstance(obj, decimal.Decimal):
93
        return str(obj)
94
    raise TypeError
95

96
data = {"value": decimal.Decimal("123.456")}
97
result = orjson.dumps(data, default=default_handler)
98
```
99

100
### JSON Deserialization
101

102
Parses JSON input to Python objects with strict UTF-8 and RFC 8259 compliance.
103

104
```python { .api }
105
def loads(__obj: bytes | bytearray | memoryview | str) -> Any:
106
    """
107
    Deserialize JSON to Python objects.
108
    
109
    Args:
110
        __obj: JSON input to parse (positional only)
111
    
112
    Returns:
113
        Parsed Python object (dict, list, int, float, str, bool, None)
114
        
115
    Raises:
116
        JSONDecodeError: On parsing failures
117
    """
118
```
119

120
**Input types**: Accepts `bytes`, `bytearray`, `memoryview`, and `str`. For best performance, pass binary data directly rather than converting to string first.
121

122
**Output types**: Always returns standard Python types: `dict`, `list`, `int`, `float`, `str`, `bool`, `None`.
123

124
### Pre-serialized JSON Fragments
125

126
Include already-serialized JSON content without re-parsing for performance optimization.
127

128
```python { .api }
129
class Fragment(tuple):
130
    """
131
    Container for pre-serialized JSON content.
132
    
133
    Args:
134
        contents: Pre-serialized JSON as bytes or str (positional only)
135
    """
136
    
137
    contents: bytes | str
138
```
139

140
**Usage example**:
141

142
```python
143
import orjson
144

145
# Include cached JSON without parsing
146
cached_json = '{"nested": {"data": [1, 2, 3]}}'
147
data = {
148
    "key": "value",
149
    "cached": orjson.Fragment(cached_json)
150
}
151

152
result = orjson.dumps(data)
153
# Output: b'{"key":"value","cached":{"nested":{"data":[1,2,3]}}}'
154
```
155

156
### Error Handling
157

158
Exception classes for JSON processing errors.
159

160
```python { .api }
161
class JSONDecodeError(json.JSONDecodeError):
162
    """
163
    Exception raised when JSON parsing fails.
164
    Inherits from json.JSONDecodeError for compatibility with standard library.
165
    """
166

167
class JSONEncodeError(TypeError):
168
    """
169
    Exception raised when JSON serialization fails.
170
    Inherits from TypeError for compatibility with standard library.
171
    """
172
```
173

174
## Serialization Options
175

176
Options are integer constants that can be combined with bitwise OR (`|`) to control serialization behavior.
177

178
### Output Formatting Options
179

180
```python { .api }
181
OPT_APPEND_NEWLINE: int  # Append \n to output
182
OPT_INDENT_2: int        # Pretty-print with 2-space indentation
183
OPT_SORT_KEYS: int       # Sort dictionary keys in output
184
```
185

186
**Usage example**:
187

188
```python
189
import orjson
190

191
data = {"b": 1, "c": 2, "a": 3}
192

193
# Pretty-printed, sorted output with newline
194
result = orjson.dumps(
195
    data, 
196
    option=orjson.OPT_INDENT_2 | orjson.OPT_SORT_KEYS | orjson.OPT_APPEND_NEWLINE
197
)
198
```
199

200
### Datetime Serialization Options
201

202
```python { .api }
203
OPT_NAIVE_UTC: int           # Treat naive datetimes as UTC
204
OPT_OMIT_MICROSECONDS: int   # Don't serialize microseconds
205
OPT_UTC_Z: int               # Use 'Z' suffix for UTC instead of '+00:00'
206
```
207

208
**Usage example**:
209

210
```python
211
import orjson
212
import datetime
213

214
dt = datetime.datetime(2023, 1, 1, 12, 0, 0, 123456)
215

216
# Standard format
217
orjson.dumps(dt)  # b'"2023-01-01T12:00:00.123456"'
218

219
# UTC with Z suffix, no microseconds
220
orjson.dumps(dt, option=orjson.OPT_NAIVE_UTC | orjson.OPT_UTC_Z | orjson.OPT_OMIT_MICROSECONDS)
221
# b'"2023-01-01T12:00:00Z"'
222
```
223

224
### Key and Type Handling Options
225

226
```python { .api }
227
OPT_NON_STR_KEYS: int      # Allow non-string dictionary keys
228
OPT_STRICT_INTEGER: int    # Enforce 53-bit integer limit (JavaScript compatibility)
229
```
230

231
**Usage example**:
232

233
```python
234
import orjson
235
import datetime
236
import uuid
237

238
# Dictionary with various key types
239
data = {
240
    "string_key": "value1",
241
    42: "value2", 
242
    datetime.date(2023, 1, 1): "value3",
243
    uuid.UUID("12345678-1234-5678-1234-123456789abc"): "value4"
244
}
245

246
result = orjson.dumps(data, option=orjson.OPT_NON_STR_KEYS)
247
```
248

249
### Passthrough Options
250

251
Control whether certain types use native serialization or are passed to the `default` handler.
252

253
```python { .api }
254
OPT_PASSTHROUGH_DATACLASS: int  # Pass dataclasses to default function
255
OPT_PASSTHROUGH_DATETIME: int   # Pass datetime objects to default function  
256
OPT_PASSTHROUGH_SUBCLASS: int   # Pass subclasses to default function
257
```
258

259
**Usage example**:
260

261
```python
262
import orjson
263
import dataclasses
264

265
@dataclasses.dataclass
266
class User:
267
    id: str
268
    name: str
269
    password: str
270

271
def custom_serializer(obj):
272
    if isinstance(obj, User):
273
        return {"id": obj.id, "name": obj.name}  # Exclude password
274
    raise TypeError
275

276
user = User("123", "Alice", "secret")
277

278
# Custom serialization excluding password
279
result = orjson.dumps(
280
    user, 
281
    option=orjson.OPT_PASSTHROUGH_DATACLASS,
282
    default=custom_serializer
283
)
284
```
285

286
### Special Type Options
287

288
```python { .api }
289
OPT_SERIALIZE_NUMPY: int     # Enable numpy array/scalar serialization
290
OPT_SERIALIZE_DATACLASS: int # Deprecated (no effect in v3)
291
OPT_SERIALIZE_UUID: int      # Deprecated (no effect in v3)
292
```
293

294
**Numpy serialization example**:
295

296
```python
297
import orjson
298
import numpy as np
299

300
# Create numpy array
301
arr = np.array([[1, 2, 3], [4, 5, 6]], dtype=np.int32)
302

303
# Serialize with numpy support
304
result = orjson.dumps(arr, option=orjson.OPT_SERIALIZE_NUMPY)
305
# Output: b'[[1,2,3],[4,5,6]]'
306
```
307

308
## Performance Characteristics
309

310
- **Speed**: ~10x faster serialization, ~2x faster deserialization vs standard library
311
- **Memory**: Efficient memory usage with string key caching (2048 entries, max 64 bytes per key)
312
- **Threading**: GIL held during operations (no thread parallelism within single call)
313
- **Optimization**: Uses AVX-512 when available on supported hardware
314
- **Compliance**: Strict UTF-8 and RFC 8259 JSON compliance
315

316
## Error Conditions
317

318
### JSONEncodeError Scenarios
319

320
- Unsupported type without `default` handler
321
- Invalid UTF-8 in string input  
322
- Integer exceeding 64-bit range (or 53-bit with `OPT_STRICT_INTEGER`)
323
- Non-string dict keys without `OPT_NON_STR_KEYS`
324
- Circular references in objects
325
- Recursion depth exceeded (254 levels in `default` function)
326
- Unsupported timezone info in datetime objects
327

328
### JSONDecodeError Scenarios
329

330
- Invalid JSON syntax
331
- Invalid UTF-8 encoding in input
332
- NaN, Infinity, -Infinity values (not valid JSON)
333
- Recursion depth exceeded (1024 levels for nested structures)
334
- Memory allocation failures for large documents
335

336
## Migration from Standard Library
337

338
Key differences when migrating from Python's built-in `json` module:
339

340
1. **Return type**: `orjson.dumps()` returns `bytes`, `json.dumps()` returns `str`
341
2. **Options**: Use `option=orjson.OPT_SORT_KEYS` instead of `sort_keys=True`  
342
3. **Indentation**: Use `option=orjson.OPT_INDENT_2` instead of `indent=2`
343
4. **Non-string keys**: Requires `option=orjson.OPT_NON_STR_KEYS`
344
5. **Native types**: Many types serialize natively (no `default` needed)
345
6. **Stricter**: orjson rejects invalid UTF-8 that `json` accepts
346

347
## Module Metadata
348

349
```python { .api }
350
__version__: str  # Library version (e.g., "3.11.3")
351
```