Install & Compatibility
Where this runs
tested against v2.0.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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.509s · 22.8MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.6s · import 0.473s · 23MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
OrjsonProvider
✓ from flask_orjson import OrjsonProvider
This quickstart demonstrates how to initialize `flask-orjson` by setting `app.json` to an instance of `OrjsonProvider`. Once configured, all Flask serialization (e.g., `jsonify`, dictionary returns) will automatically use `orjson`. It also showcases `flask-orjson`'s native support for common types like `datetime`, `date`, and `Decimal`.
from flask import Flask, jsonify
from flask_orjson import OrjsonProvider
from datetime import datetime, date
from decimal import Decimal
app = Flask(__name__)
app.json = OrjsonProvider(app)
@app.route("/")
def hello_world():
# This will use OrjsonProvider for serialization
return jsonify({"hello": "world", "current_time": datetime.now()})
@app.route("/data")
def get_data():
# OrjsonProvider natively supports datetime, date, Decimal, UUID, etc.
return {
"timestamp": datetime.now(),
"today": date.today(),
"amount": Decimal("123.45"),
"complex_list": [{"id": 1, "name": "item 1"}, {"id": 2, "name": "item 2"}]
}
if __name__ == "__main__":
app.run(debug=True)
Debug
Known issues
breaking`orjson.dumps()` returns `bytes`, not `str`, directly. While `flask-orjson` integrates this, any custom code directly calling `orjson.dumps()` and expecting a string output will break.fixIf interacting directly with `orjson.dumps()` outside of `flask-orjson`'s provider, ensure subsequent operations expect `bytes` or explicitly decode to `str` using `.decode('utf-8')` if necessary. `flask-orjson` handles this internally for Flask responses. affects: All versions of `flask-orjson` and `orjson`.
gotcha`orjson` is stricter regarding JSON compliance than Python's standard `json` module. Values like `NaN` (Not-a-Number) or `Infinity` in floats will raise a `JSONEncodeError` during serialization.fixPre-process data to handle or filter non-compliant float values (e.g., convert to `None` or a string representation) before passing them to `jsonify` or returning from a view.
affects: All versions of `flask-orjson` and `orjson`.
gotchaCustom object serialization with `orjson` uses a `default` hook function, not subclassing `json.JSONEncoder` as in the standard library. If you're migrating from a custom `JSONEncoder`, your logic will need refactoring.fixPass a `default` callable to the `OrjsonProvider` constructor. This function should take an object and return a JSON-serializable representation, or raise a `TypeError` if it cannot handle the object.
affects: All versions of `flask-orjson` and `orjson`.
gotchaDatetime and date objects are serialized to ISO 8601 format (e.g., '2026-04-16T18:02:00.000000') instead of RFC 822 (used by Flask's default provider).fixUpdate client-side applications to correctly parse ISO 8601 formatted datetime strings. If RFC 822 is strictly required, manually format datetimes before returning them.
affects: All versions of `flask-orjson`.
Errors
Common errors & fixes
orjson.JSONEncodeError: Object of type <YourCustomClass> is not JSON serializable
You are attempting to serialize a custom Python object that `orjson` does not natively support, and no `default` serialization function has been provided to handle it.
fixProvide a `default` callable function when initializing `OrjsonProvider`. This function will be called for objects that `orjson` cannot serialize by default, allowing you to convert them to a serializable type. Example: `app.json = OrjsonProvider(app, default=my_custom_serializer)`.
TypeError: Object of type Decimal is not JSON serializable
While `flask-orjson` (and `orjson` >= 3.0) supports `Decimal` natively, this error can occur if you're using an older `orjson` version or if `flask-orjson` isn't correctly configured. For other unsupported types, the cause is the same as the custom class error.
fixEnsure `flask-orjson` (version 2.0.0 and above) is correctly installed and configured. If the error persists for `Decimal` (or for other types not natively supported), define and pass a `default` callable to `OrjsonProvider` to handle the specific type. For `Decimal`, a common fix within a `default` is `return float(obj)` or `return str(obj)`.
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xff in position X: invalid start byte
This typically happens when `orjson.loads()` receives input that is not valid UTF-8 encoded bytes, or when you explicitly `decode('utf-8')` an invalid byte sequence before passing it to `orjson.loads`.
fixEnsure that the input data to `orjson.loads()` is always valid UTF-8 encoded bytes. If you're receiving data from a request, verify the client is sending correct encoding. `orjson.loads` can directly consume `bytes` or `bytearray`, so avoid unnecessary `decode()` calls if the input is already in bytes format.
Upgrade
Version history
2.0.0latest on PyPI · released Jan 15, 2024
Audit
Dependencies
FlaskrequiredCore web framework integration; requires >= 2.2.0
orjsonrequiredUnderlying fast JSON serialization library; requires >= 3.6.0