MessagePack for Python
raw JSON → 1.1.2 verified Tue May 12 auth: no python install: verified quickstart: verified
MessagePack is an efficient binary serialization format, offering a faster and smaller alternative to JSON for data exchange across multiple languages. The Python library provides CPython bindings and a pure Python implementation for reading and writing MessagePack data. The current stable version is 1.1.2, actively maintained with regular releases.
pip install msgpack Common errors
error TypeError: can't serialize <class 'your_module.YourCustomClass'> ↓
cause msgpack does not inherently know how to serialize custom Python objects or certain complex built-in types (like datetime or set), requiring a custom serialization function.
fix
Provide a
default function to msgpack.packb() that converts unsupported types into a MessagePack-serializable format, often by representing them as dictionaries or using ExtType for custom types.
import msgpack
import datetime
def default_serializer(obj):
if isinstance(obj, datetime.datetime):
return {'__datetime__': obj.isoformat()}
# Add other custom types here
raise TypeError(f"Object of type {obj.__class__.__name__} is not JSON serializable")
data = {'timestamp': datetime.datetime.now(), 'value': 123}
packed_data = msgpack.packb(data, default=default_serializer)
print(packed_data)
# To unpack, you'd need a corresponding object hook or ext_hook
# For simplicity, here's a basic unpack for the example above:
def datetime_object_hook(obj):
if '__datetime__' in obj:
return datetime.datetime.fromisoformat(obj['__datetime__'])
return obj
unpacked_data = msgpack.unpackb(packed_data, raw=False, object_hook=datetime_object_hook)
print(unpacked_data) error msgpack.exceptions.ExtraData: unpack(b) received extra data. ↓
cause This error occurs when `msgpack.unpackb()` is given a byte string that contains more than one complete MessagePack object, or unexpected trailing data after a single object.
fix
When dealing with streams or concatenated MessagePack objects, use
msgpack.Unpacker to process data incrementally, or ensure unpackb() receives only a single, complete MessagePack object.
import msgpack
# Example of multiple objects packed together (causes ExtraData with unpackb)
packed_data_stream = msgpack.packb({'a': 1}) + msgpack.packb({'b': 2})
# Incorrect: will raise ExtraData
try:
obj = msgpack.unpackb(packed_data_stream)
except msgpack.exceptions.ExtraData as e:
print(f"Caught expected error: {e}")
# Correct: using Unpacker for stream processing
unpacker = msgpack.Unpacker(raw=False) # raw=False for Python strings
unpacker.feed(packed_data_stream)
for obj in unpacker:
print(f"Unpacked object: {obj}") error ValueError: Unpack failed: incomplete input ↓
cause The input bytes provided to `msgpack.unpackb()` are truncated, corrupted, or do not contain enough data to form a complete and valid MessagePack object.
fix
Ensure the input byte string is a complete and valid MessagePack object. When reading from a stream or network, confirm that all parts of the MessagePack message have been received before attempting to unpack. Use
msgpack.Unpacker's feed method and iterate over it to handle partial data gracefully.
import msgpack
# Example of incomplete data
incomplete_data = msgpack.packb({'key': 'value'})[:-5] # Truncate 5 bytes
# Incorrect: will raise ValueError
try:
obj = msgpack.unpackb(incomplete_data)
except ValueError as e:
print(f"Caught expected error: {e}")
# Correct: When data might be incomplete, use Unpacker
unpacker = msgpack.Unpacker(raw=False)
# Simulate receiving data in chunks
unpacker.feed(incomplete_data)
# The loop won't yield anything until a complete object is fed
for obj in unpacker:
print(f"Unpacked object: {obj}")
# If later, the rest of the data arrives
remaining_data = msgpack.packb({'key': 'value'})[-5:] # The missing 5 bytes
unpacker.feed(remaining_data)
for obj in unpacker:
print(f"Successfully unpacked with remaining data: {obj}") error UnicodeDecodeError: 'utf-8' codec can't decode byte 0x... in position ...: invalid start byte ↓
cause This error occurs during unpacking when MessagePack attempts to decode a byte sequence as a UTF-8 string, but the sequence actually represents raw binary data or is not valid UTF-8. This often happens when `bytes` objects are packed without `use_bin_type=True` or unpacked with default settings that try to interpret everything as strings.
fix
When packing, ensure
bytes objects are treated as MessagePack's binary type by passing use_bin_type=True to msgpack.packb(). When unpacking, pass raw=False to msgpack.unpackb() or msgpack.Unpacker to automatically decode MessagePack string types to Python str, while preserving MessagePack binary types as Python bytes.
import msgpack
# Scenario 1: Packing bytes without use_bin_type=True (problematic)
binary_data = b'\x80\x01\x02\x03' # Non-UTF-8 bytes
try:
# This might pack it as a raw string if use_bin_type is not explicit
packed_raw = msgpack.packb(binary_data, use_bin_type=False)
# Unpacking without raw=True (Python 3 default) will try to decode as string
# and fail if the packed 'raw' contains invalid UTF-8
# In msgpack 1.1.2, use_bin_type=True is often default/recommended.
# However, if explicitly set to False during packing and then unpacked without raw=True (default), it can cause this.
print("Attempting to unpack potentially problematic data...")
msgpack.unpackb(packed_raw, raw=False)
except UnicodeDecodeError as e:
print(f"Caught expected UnicodeDecodeError: {e}")
# Correct way: Pack bytes as MessagePack's binary type
packed_correctly = msgpack.packb(binary_data, use_bin_type=True)
# Unpack with raw=False (default for Python strings) to get correct Python types
unpacked_data = msgpack.unpackb(packed_correctly, raw=False)
print(f"Unpacked correctly (bytes object): {unpacked_data}")
# If you specifically want raw bytes for strings as well, use raw=True during unpacking
packed_str = msgpack.packb('hello world')
unpacked_raw_str = msgpack.unpackb(packed_str, raw=True)
print(f"Unpacked string as bytes: {unpacked_raw_str}") error TypeError: Cannot serialize 'datetime.datetime' object ↓
cause `msgpack` does not natively serialize all Python types like `datetime` objects, requiring a custom serialization handler.
fix
Provide a
default function to msgpack.packb to convert unsupported types (e.g., datetime) into a serializable format like an ISO string or timestamp.
import msgpack
import datetime
def default_serializer(obj):
if isinstance(obj, datetime.datetime):
return obj.isoformat()
raise TypeError(f"Object of type {obj.__class__.__name__} is not msgpack serializable")
data = {'timestamp': datetime.datetime.now()}
packed_data = msgpack.packb(data, default=default_serializer)
print(packed_data) Warnings
breaking The PyPI package name changed from `msgpack-python` to `msgpack` in version 0.5. When upgrading from older versions (0.4 or earlier), you must `pip uninstall msgpack-python` before running `pip install -U msgpack` to avoid conflicts and ensure the correct package is used. ↓
fix Uninstall the old `msgpack-python` package: `pip uninstall msgpack-python`, then install the current package: `pip install msgpack`.
breaking Version 1.0 introduced several breaking changes: dropped Python 2 support for the C extension (pure Python fallback is used), `Packer.use_bin_type` now defaults to `True` (bytes are encoded in bin type), the `encoding` option was removed (UTF-8 is always used), `Unpacker.raw` now defaults to `False` (decodes to Python `str`), and default `max_buffer_size` changed to 100MiB with `strict_map_key` defaulting to `True`. ↓
fix Review your packing/unpacking calls: use `raw=True` for unpacking if raw bytes are expected or for old formats; use `use_bin_type=False` if you need to pack into the old 'raw' type. Adjust `max_buffer_size` or `strict_map_key=False` if dealing with large/unusual data or old formats.
gotcha When packing or unpacking data containing binary strings or interacting with older MessagePack formats, the default settings for `use_bin_type` and `raw` might lead to unexpected behavior (e.g., `UnicodeDecodeError`). By default, `packb` uses `use_bin_type=True` for `bytes` (new spec 'bin' type), and `unpackb` uses `raw=False` to decode to `str`. ↓
fix Explicitly set `use_bin_type=False` during packing to use the old 'raw' type, and `raw=True` during unpacking if you need Python `bytes` objects instead of decoded `str` objects, especially when dealing with non-UTF-8 compatible binary data or older MessagePack implementations.
gotcha MessagePack does not automatically serialize complex custom Python objects (e.g., instances of user-defined classes). Attempting to pack such objects directly will result in a `TypeError`. ↓
fix Implement custom serialization logic by providing a `default` callable to `msgpack.packb()` (or `Packer`) to convert custom objects into MessagePack-supported types. For deserialization, use an `object_hook` or `ext_hook` callable with `msgpack.unpackb()` (or `Unpacker`) to reconstruct your custom objects.
gotcha When performing file I/O with `msgpack.pack()` and `msgpack.unpack()`, always open files in binary mode (`'wb'` for writing, `'rb'` for reading). Using text mode (`'w'` or `'r'`) will corrupt the binary MessagePack data. ↓
fix Ensure file opening modes are always specified as binary, e.g., `with open('data.msgpack', 'wb') as f:`.
Install compatibility verified last tested: 2026-05-12
python os / libc status wheel install import disk
3.10 alpine (musl) - - 0.01s 18.8M
3.10 alpine (musl) - - 0.01s 18.8M
3.10 slim (glibc) - - 0.00s 20M
3.10 slim (glibc) - - 0.00s 20M
3.11 alpine (musl) - - 0.01s 20.7M
3.11 alpine (musl) - - 0.01s 20.7M
3.11 slim (glibc) - - 0.01s 22M
3.11 slim (glibc) - - 0.01s 22M
3.12 alpine (musl) - - 0.00s 12.6M
3.12 alpine (musl) - - 0.00s 12.6M
3.12 slim (glibc) - - 0.00s 13M
3.12 slim (glibc) - - 0.00s 13M
3.13 alpine (musl) - - 0.00s 12.2M
3.13 alpine (musl) - - 0.00s 12.3M
3.13 slim (glibc) - - 0.00s 13M
3.13 slim (glibc) - - 0.00s 13M
3.9 alpine (musl) - - 0.01s 18.3M
3.9 alpine (musl) - - 0.00s 18.3M
3.9 slim (glibc) - - 0.01s 19M
3.9 slim (glibc) - - 0.00s 19M
Imports
- msgpack
import msgpack - ExtType
from msgpack import ExtType - Timestamp
from msgpack import Timestamp
Quickstart verified last tested: 2026-04-23
import msgpack
import os
data_to_pack = {
'name': 'Alice',
'age': 30,
'is_student': True,
'grades': [95, 88, 72.5]
}
# Serialize data to bytes
packed_data = msgpack.packb(data_to_pack)
print(f"Packed data (bytes): {packed_data}")
# Deserialize data from bytes
unpacked_data = msgpack.unpackb(packed_data, raw=False)
print(f"Unpacked data: {unpacked_data}")
# Example with file I/O
file_path = os.path.join(os.path.dirname(__file__), 'example.msgpack')
with open(file_path, 'wb') as f:
msgpack.pack(data_to_pack, f)
with open(file_path, 'rb') as f:
loaded_data = msgpack.unpack(f, raw=False)
print(f"Loaded data from file: {loaded_data}")
os.remove(file_path)