{"id":791,"library":"ormsgpack","title":"ormsgpack","description":"ormsgpack is a fast MessagePack serialization library for Python, derived from orjson, offering native support for dataclasses, datetimes, and NumPy arrays. It prioritizes performance and correctness, follows semantic versioning, and releases frequent updates to support new Python versions and add features.","status":"active","version":"1.12.2","language":"python","source_language":"en","source_url":"https://github.com/ormsgpack/ormsgpack","tags":["msgpack","serialization","performance","dataclasses","numpy","pydantic","binary"],"install":[{"cmd":"pip install ormsgpack","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"For native serialization of NumPy arrays and types like ndarray, float32, etc.","package":"numpy","optional":true},{"reason":"For native serialization of Pydantic BaseModel instances.","package":"pydantic","optional":true}],"imports":[{"wrong":"import ormsgpack","symbol":"ormsgpack","correct":"import ormsgpack"},{"wrong":"ormsgpack.packb","symbol":"packb","correct":"from ormsgpack import packb"},{"wrong":"ormsgpack.unpackb","symbol":"unpackb","correct":"from ormsgpack import unpackb"}],"quickstart":{"code":"import ormsgpack\nimport datetime\nimport numpy\n\n# Example data including datetime and numpy array\nevent = {\n    \"type\": \"put\",\n    \"time\": datetime.datetime(1970, 1, 1, tzinfo=datetime.timezone.utc),\n    \"uid\": 1,\n    \"data\": numpy.array([1, 2, 3], dtype=numpy.int64),\n}\n\n# Serialize the data with an option to handle NumPy arrays\npacked_data = ormsgpack.packb(event, option=ormsgpack.OPT_SERIALIZE_NUMPY)\nprint(f\"Packed data: {packed_data}\")\n\n# Deserialize the data\nunpacked_data = ormsgpack.unpackb(packed_data)\nprint(f\"Unpacked data: {unpacked_data}\")\n\n# Verify types (Note: NumPy arrays deserialize to lists by default unless a custom hook is used)\nassert isinstance(unpacked_data, dict)\nassert isinstance(unpacked_data['time'], str) # datetime serializes to ISO 8601 string by default\nassert isinstance(unpacked_data['data'], list)\nassert unpacked_data['data'] == [1, 2, 3]","lang":"python","description":"This quickstart demonstrates how to serialize a Python dictionary containing a datetime object and a NumPy array into MessagePack format, and then deserialize it back. It shows the use of `packb` with an option for NumPy serialization and `unpackb` for deserialization."},"warnings":[{"fix":"Upgrade Python to 3.10+ or pin ormsgpack to a compatible version (e.g., `<1.12.0` for Python 3.9, `<1.7.0` for Python 3.8).","message":"ormsgpack dropped support for Python 3.9 in version 1.12.0 and Python 3.8 in version 1.7.0. Users on older Python versions must use an earlier ormsgpack version.","severity":"breaking","affected_versions":"<1.12.0 for Python 3.9, <1.7.0 for Python 3.8"},{"fix":"Ensure dictionary keys are simple types (strings, numbers, basic Python objects) or use a custom `default` hook to convert complex keys to supported types before serialization.","message":"`packb` started rejecting dictionary keys that are nested dataclasses or Pydantic models in version 1.8.0. This change was implemented to prevent potential issues with complex key serialization.","severity":"breaking","affected_versions":">=1.8.0"},{"fix":"Always explicitly raise an exception in the `default` callable for types it doesn't handle, for example: `raise TypeError(f\"Object of type {type(obj).__name__} is not msgpack serializable\")`.","message":"When providing a `default` callable to `packb` for custom type serialization, it must explicitly raise an exception (e.g., `TypeError`) if it cannot handle a given type. If it implicitly returns `None`, `ormsgpack` will serialize `None` as a valid value, potentially leading to unexpected data.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be aware of potential key collisions when using `OPT_NON_STR_KEYS`. Consider standardizing keys to strings or ensuring unique string representations for all keys.","message":"Using the `OPT_NON_STR_KEYS` option for dictionary keys can lead to duplicate keys if different non-string objects serialize to the same string representation. For example, `{'1970-01-01T00:00:00+00:00': True, datetime.datetime(1970, 1, 1, 0, 0, 0): False}` could result in a single key after serialization.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For versions <1.12.0, explicitly use `option=ormsgpack.OPT_REPLACE_SURROGATES` if you expect to serialize strings with surrogate code points. Upgrading to 1.12.0 or newer is recommended for improved performance and fixes.","message":"While not a breaking change in current behavior, prior to version 1.12.0, serializing strings containing surrogate code points (e.g., ill-formed UTF-8) required the `OPT_REPLACE_SURROGATES` option to prevent errors. Version 1.12.0 added this option and improved handling.","severity":"deprecated","affected_versions":"<1.12.0"},{"fix":"Ensure 'numpy' is listed as a dependency in your `requirements.txt` or `setup.py` and is installed in the environment before running the script. For example, add `numpy` to your `pip install` command.","message":"The script failed because the 'numpy' package was not found. This indicates that 'numpy' was not installed in the environment.","severity":"breaking","affected_versions":"All versions"},{"fix":"Install the 'numpy' package using pip (e.g., `pip install numpy`) or ensure that 'numpy' is included in the project's dependency management system (e.g., `requirements.txt`).","message":"The 'numpy' module is not found, causing a 'ModuleNotFoundError'. This indicates that a required external dependency is missing from the environment.","severity":"breaking","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'add':41 'array':22 'binari':49 'correct':27 'dataclass':18,46 'datetim':19 'deriv':11 'fast':5 'featur':42 'follow':28 'frequent':33 'librari':8 'messagepack':6 'msgpack':43 'nativ':15 'new':37 'numpi':21,47 'offer':14 'orjson':13 'ormsgpack':1,2 'perform':25,45 'priorit':24 'pydant':48 'python':10,38 'releas':32 'semant':29 'serial':7,44 'support':16,36 'updat':34 'version':30,39","created_at":"2026-03-29T04:21:51.412617+00:00","updated_at":"2026-04-16T17:48:49.833824+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"1.12.2","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/ormsgpack/ormsgpack","docs":null,"changelog":null,"pypi":"https://pypi.org/project/ormsgpack/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-30","last_verified":"2026-08-27","next_check":"2026-07-30","install_tag":"verified"}}