{"id":8996,"library":"flask-orjson","title":"Flask-ORJSON","description":"Flask-ORJSON is a Flask JSON provider that leverages the `orjson` library for significantly faster JSON serialization and deserialization. It replaces Flask's default `json` module with `orjson`, offering performance improvements, especially for high-throughput applications handling large JSON payloads. The current version is 2.0.0, and it is actively maintained by the Pallets-eco team, following a release cadence tied to Flask and `orjson` updates.","status":"active","version":"2.0.0","language":"en","source_language":"en","source_url":"https://github.com/davidism/flask-orjson/","tags":["flask","json","serialization","performance","orjson"],"install":[{"cmd":"pip install flask-orjson","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core web framework integration; requires >= 2.2.0","package":"Flask","optional":false},{"reason":"Underlying fast JSON serialization library; requires >= 3.6.0","package":"orjson","optional":false}],"imports":[{"symbol":"OrjsonProvider","correct":"from flask_orjson import OrjsonProvider"}],"quickstart":{"code":"from flask import Flask, jsonify\nfrom flask_orjson import OrjsonProvider\nfrom datetime import datetime, date\nfrom decimal import Decimal\n\napp = Flask(__name__)\napp.json = OrjsonProvider(app)\n\n@app.route(\"/\")\ndef hello_world():\n    # This will use OrjsonProvider for serialization\n    return jsonify({\"hello\": \"world\", \"current_time\": datetime.now()})\n\n@app.route(\"/data\")\ndef get_data():\n    # OrjsonProvider natively supports datetime, date, Decimal, UUID, etc.\n    return {\n        \"timestamp\": datetime.now(),\n        \"today\": date.today(),\n        \"amount\": Decimal(\"123.45\"),\n        \"complex_list\": [{\"id\": 1, \"name\": \"item 1\"}, {\"id\": 2, \"name\": \"item 2\"}]\n    }\n\nif __name__ == \"__main__\":\n    app.run(debug=True)","lang":"python","description":"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`."},"warnings":[{"fix":"If 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.","message":"`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.","severity":"breaking","affected_versions":"All versions of `flask-orjson` and `orjson`."},{"fix":"Pre-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.","message":"`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.","severity":"gotcha","affected_versions":"All versions of `flask-orjson` and `orjson`."},{"fix":"Pass 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.","message":"Custom 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.","severity":"gotcha","affected_versions":"All versions of `flask-orjson` and `orjson`."},{"fix":"Update client-side applications to correctly parse ISO 8601 formatted datetime strings. If RFC 822 is strictly required, manually format datetimes before returning them.","message":"Datetime 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).","severity":"gotcha","affected_versions":"All versions of `flask-orjson`."}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Provide 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)`.","cause":"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.","error":"orjson.JSONEncodeError: Object of type <YourCustomClass> is not JSON serializable"},{"fix":"Ensure `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)`.","cause":"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.","error":"TypeError: Object of type Decimal is not JSON serializable"},{"fix":"Ensure 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.","cause":"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`.","error":"UnicodeDecodeError: 'utf-8' codec can't decode byte 0xff in position X: invalid start byte"}]}