{"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":[{"note":"Main function for serializing Python objects to MessagePack bytes.","symbol":"packb","correct":"import ormsgpack\npacked_data = ormsgpack.packb(data)"},{"note":"Main function for deserializing MessagePack bytes to Python objects.","symbol":"unpackb","correct":"import ormsgpack\nunpacked_data = ormsgpack.unpackb(packed_data)"},{"note":"An example of an option constant used to modify serialization behavior.","symbol":"OPT_SERIALIZE_NUMPY","correct":"import ormsgpack\npacked_data = ormsgpack.packb(data, option=ormsgpack.OPT_SERIALIZE_NUMPY)"}],"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,"last_verified":"2026-05-12T19:11:03.093Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"fix":"Provide a `default` callable to `ormsgpack.packb()` that explicitly handles the serialization of the unsupported type. This function should return a natively serializable type or raise a TypeError if the object cannot be handled.","cause":"ormsgpack encountered an object type that it does not natively know how to serialize into MessagePack format. This often occurs with custom classes, certain datetime objects, or other non-primitive types.","error":"TypeError: Type is not msgpack serializable: YourCustomObject"},{"fix":"Install the package using pip: `pip install ormsgpack`. If using virtual environments, ensure you activate the correct environment before installation.","cause":"The 'ormsgpack' package is not installed in the currently active Python environment, or the environment in which it was installed is not the one being used.","error":"ModuleNotFoundError: No module named 'ormsgpack'"},{"fix":"Ensure that the data passed to `ormsgpack.unpackb()` is a `bytes` object. For example, convert a string to bytes using `.encode('utf-8')` if it represents MessagePack data.","cause":"The input provided to `ormsgpack.unpackb()` is not a `bytes` object, which is required for deserialization.","error":"ormsgpack.MsgpackDecodeError: unpack requires a bytes object"},{"fix":"Install Rust and Cargo development tools before attempting to install ormsgpack. The recommended way is via `rustup.rs` or your system's package manager (e.g., `apt install rust-all` on Debian/Ubuntu, `brew install rust` on macOS).","cause":"ormsgpack is a Rust-based library. If a pre-built wheel (binary distribution) is not available for your specific system or Python version, pip will attempt to build it from source, which requires the Rust toolchain (including Cargo) to be installed on your system.","error":"error: subprocess-exited-with-error ... Cargo, the Rust package manager, is not installed or is not on PATH."},{"fix":"Use the `ormsgpack.OPT_PASSTHROUGH_BIG_INT` option with `packb()` and provide a `default` function to handle these very large integers, typically by converting them to strings or a custom extension type.","cause":"Attempting to serialize a Python integer that is larger than the 64-bit integer range supported by MessagePack without enabling the appropriate option for handling large integers.","error":"TypeError: Integer exceeds 64-bit range"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"1.12.2","cli_name":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":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.7,"disk_size":"18.8M"},{"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.7,"disk_size":"18.8M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.7,"import_time_s":0.03,"mem_mb":1.7,"disk_size":"19M"},{"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.02,"mem_mb":1.7,"disk_size":"19M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":1.6,"disk_size":"20.6M"},{"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.06,"mem_mb":1.6,"disk_size":"20.6M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.6,"import_time_s":0.05,"mem_mb":1.6,"disk_size":"21M"},{"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.04,"mem_mb":1.6,"disk_size":"21M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.3,"disk_size":"12.5M"},{"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.3,"disk_size":"12.5M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.5,"import_time_s":0.04,"mem_mb":1.3,"disk_size":"12M"},{"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.04,"mem_mb":1.3,"disk_size":"12M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":2,"disk_size":"12.2M"},{"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.5,"disk_size":"12.1M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.5,"import_time_s":0.04,"mem_mb":1.8,"disk_size":"12M"},{"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.3,"disk_size":"12M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.7,"disk_size":"18.2M"},{"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.7,"disk_size":"18.2M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.9,"import_time_s":0.03,"mem_mb":1.7,"disk_size":"18M"},{"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.03,"mem_mb":1.7,"disk_size":"18M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}