Install & Compatibility
Where this runs
tested against v1.12.2 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.040s · 18.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.038s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ormsgpack
✓ import ormsgpack
✗ import ormsgpack
packb
✓ from ormsgpack import packb
✗ ormsgpack.packb
unpackb
✓ from ormsgpack import unpackb
✗ ormsgpack.unpackb
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.
import ormsgpack
import datetime
import numpy
# Example data including datetime and numpy array
event = {
"type": "put",
"time": datetime.datetime(1970, 1, 1, tzinfo=datetime.timezone.utc),
"uid": 1,
"data": numpy.array([1, 2, 3], dtype=numpy.int64),
}
# Serialize the data with an option to handle NumPy arrays
packed_data = ormsgpack.packb(event, option=ormsgpack.OPT_SERIALIZE_NUMPY)
print(f"Packed data: {packed_data}")
# Deserialize the data
unpacked_data = ormsgpack.unpackb(packed_data)
print(f"Unpacked data: {unpacked_data}")
# Verify types (Note: NumPy arrays deserialize to lists by default unless a custom hook is used)
assert isinstance(unpacked_data, dict)
assert isinstance(unpacked_data['time'], str) # datetime serializes to ISO 8601 string by default
assert isinstance(unpacked_data['data'], list)
assert unpacked_data['data'] == [1, 2, 3]
Debug
Known issues
breakingormsgpack 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.fixUpgrade 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).
affects: <1.12.0 for Python 3.9, <1.7.0 for Python 3.8
breaking`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.fixEnsure 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.
affects: >=1.8.0
gotchaWhen 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.fixAlways 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")`. affects: All versions
gotchaUsing 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.fixBe aware of potential key collisions when using `OPT_NON_STR_KEYS`. Consider standardizing keys to strings or ensuring unique string representations for all keys.
affects: All versions
deprecatedWhile 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.fixFor 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.
affects: <1.12.0
breakingThe script failed because the 'numpy' package was not found. This indicates that 'numpy' was not installed in the environment.fixEnsure '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.
affects: All versions
breakingThe 'numpy' module is not found, causing a 'ModuleNotFoundError'. This indicates that a required external dependency is missing from the environment.fixInstall 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`).
affects: All versions
Upgrade
Version history
1.12.2latest on PyPI · released Jan 18, 2026
Audit
Dependencies
numpyoptionalFor native serialization of NumPy arrays and types like ndarray, float32, etc.
pydanticoptionalFor native serialization of Pydantic BaseModel instances.