Install & Compatibility
Where this runs
tested against v5.10.0 · 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.236s · 36.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.3s · import 0.210s · 38MB
39MB installed
● package 39MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
jsonutils
✓ from oslo_serialization import jsonutils
✗ import oslo_serialization.jsonutils
While 'import oslo_serialization.jsonutils' works, directly importing the module is the standard and cleaner approach for accessing its functions like dumps, loads, and to_primitive.
This quickstart demonstrates how to use `oslo_serialization.jsonutils.dumps` and `loads` to serialize and deserialize a custom Python object. It highlights the automatic handling of types like `datetime` and `UUID` by `jsonutils.to_primitive`, which `dumps` utilizes by default.
from oslo_serialization import jsonutils
import datetime
import uuid
class CustomObject:
def __init__(self, name, value, created_at=None):
self.name = name
self.value = value
self.id = str(uuid.uuid4())
self.created_at = created_at or datetime.datetime.now(datetime.timezone.utc)
# oslo_serialization.jsonutils.to_primitive will handle this automatically
# but for custom types, you might explicitly define how to convert them.
# For datetime and UUID, jsonutils has built-in support.
def to_dict(self):
return {
'name': self.name,
'value': self.value,
'id': self.id,
'created_at': self.created_at.isoformat()
}
# Example usage
obj = CustomObject('test_item', 123.45)
# Serialize to JSON string
json_string = jsonutils.dumps(obj, indent=2)
print(f"Serialized JSON:\n{json_string}")
# Deserialize from JSON string
data_dict = jsonutils.loads(json_string)
print(f"Deserialized dictionary: {data_dict}")
# Demonstrate to_primitive (used internally by dumps by default)
primitive_data = jsonutils.to_primitive(obj)
print(f"Primitive representation: {primitive_data}")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'oslo_serialization'
The 'oslo-serialization' library is not installed in the current Python environment, or there's a typo in the import statement.
fixEnsure the library is installed using pip: `pip install oslo-serialization`
ValueError: Cannot convert <value> to primitive
The `oslo_serialization.jsonutils.dumps` function, which relies on `to_primitive` by default, encountered an object type (e.g., a custom class instance without a `to_dict` method) that it cannot automatically serialize into a basic JSON-compatible type. This behavior became an explicit `ValueError` in newer versions of the library.
fixDefine a `to_dict` method on your custom object that returns a dictionary representation, or provide a custom `default` callable function to `jsonutils.dumps` to handle the non-primitive type.
Could not deserialize msgpack message: unpack(b) received extra data
This error, originating from the underlying `msgpack` library, indicates that the MessagePack data being unpacked is either corrupted, incomplete, or contains unexpected trailing bytes after a valid MessagePack object.
fixVerify that the source of the MessagePack data is sending complete and correctly formatted messages. Ensure no extra data is appended to the MessagePack payload before deserialization.
unpackb() got an unexpected keyword argument 'max_buffer_size'
This issue occurs when attempting to pass the `max_buffer_size` argument to `msgpack.unpackb()` (or a similar one-shot unpacking function in `oslo_serialization.msgpackutils`) which does not support this argument directly. This argument is typically for the `msgpack.Unpacker` object for stream-based unpacking.
fixRemove the `max_buffer_size` argument when using `unpackb()`. If handling large data and needing buffer control, use `msgpack.Unpacker` directly with its `max_buffer_size` parameter, feeding data in chunks.
Upgrade
Version history
5.11.0latest on PyPI · released Jul 10, 2026
Audit
Dependencies
oslo.utilsrequiredProvides core utility functions used by oslo.serialization.
msgpack-pythonoptionalRequired for MessagePack serialization support (imported as `msgpack`).
PyYAMLoptionalRequired for YAML serialization, though the `yamlutils` module is deprecated.