{"id":410,"library":"orjson","title":"orjson","description":"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.","status":"active","version":"3.11.7","language":"python","source_language":"en","source_url":"https://github.com/ijl/orjson","tags":["JSON","serialization","deserialization","Python","orjson"],"install":[{"cmd":"pip install orjson","lang":"bash","label":"Install orjson"}],"dependencies":[],"imports":[{"note":"Ensure correct import path to avoid ImportError.","symbol":"orjson","correct":"import orjson"}],"quickstart":{"code":"import orjson\n\n# Serialize a Python object to JSON\ndata = {'name': 'Alice', 'age': 30}\njson_bytes = orjson.dumps(data)\njson_str = json_bytes.decode('utf-8')\nprint(json_str)\n\n# Deserialize JSON to a Python object\njson_bytes = b'{\"name\":\"Alice\",\"age\":30}'\nparsed_data = orjson.loads(json_bytes)\nprint(parsed_data)","lang":"python","description":"A simple example demonstrating serialization and deserialization using orjson."},"warnings":[{"fix":"Ensure that all JSON input passed to orjson.loads() is encoded in UTF-8.","message":"orjson 3.11.7 introduces a breaking change in the deserialization function, requiring explicit UTF-8 encoding for JSON input.","severity":"breaking","affected_versions":"3.11.7"},{"fix":"Ensure all objects passed to orjson.dumps() are serializable, or handle exceptions appropriately.","message":"Using orjson.dumps() on non-serializable objects will raise a TypeError.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-12T13:39:14.578Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"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`.","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.","error":"orjson.JSONEncodeError: Type is not JSON serializable: <class 'your_module.YourCustomObject'>"},{"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.","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.","error":"orjson.JSONDecodeError: str is not valid UTF-8: surrogates not allowed"},{"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.","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.","error":"TypeError: dumps() got an unexpected keyword argument 'indent'"},{"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')`.","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`.","error":"TypeError: a bytes-like object is required, not 'str'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.8,"disk_size":"18.1M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.8,"disk_size":"19M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":1.7,"disk_size":"19.9M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":1.7,"disk_size":"20M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.4,"disk_size":"11.8M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":1.4,"disk_size":"12M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.6,"disk_size":"11.5M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.4,"disk_size":"12M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.8,"disk_size":"17.6M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.8,"disk_size":"18M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}