Install & Compatibility
Where this runs
tested against v0.8.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.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 67.1MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.7s · import 0.000s · 20MB
42MB installed
● package 42MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
packb
✓ from msgpack_stubs import packb
✗ import msgpack
unpackb
✓ from msgpack_stubs import unpackb
✗ import msgpack
This quickstart demonstrates how to use the underlying `msgpack` library, with `msgpack-types` providing static type checking. After installing `msgpack-types`, a type checker like MyPy will analyze the `msgpack.packb` and `msgpack.unpackb` calls, ensuring correct argument types and inferring return types, as shown in the function signatures.
import msgpack
def process_data(data: dict) -> bytes:
packed = msgpack.packb(data, use_bin_type=True)
return packed
def decode_data(packed_data: bytes) -> dict:
# raw=False decodes binary strings to Python str (UTF-8 assumed)
unpacked = msgpack.unpackb(packed_data, raw=False)
return unpacked # type: ignore
my_data = {'name': 'Alice', 'age': 30, 'cities': ['New York', 'London']}
# Using the functions with type hints
encoded = process_data(my_data)
decoded = decode_data(encoded)
print(f"Original: {my_data}")
print(f"Encoded: {encoded}")
print(f"Decoded: {decrypted}")
# Example of type checking with MyPy (after installing msgpack-types):
# If you were to do `process_data('not a dict')`, MyPy would flag a type error.
Debug
Known issues
gotchaWhen unpacking, the `raw` parameter in `msgpack.unpackb` (and `Unpacker`) determines whether 'str' (raw) types in MessagePack are decoded to Python `bytes` (`raw=True`) or `str` (Unicode, `raw=False`). The default for `msgpack>=1.0` is `raw=False`, assuming UTF-8. Be explicit to avoid encoding/decoding issues.fixAlways explicitly set `raw=True` or `raw=False` in `msgpack.unpackb` and `msgpack.Unpacker` constructor to match expected data types. For example: `msgpack.unpackb(data, raw=False)` for UTF-8 strings or `msgpack.unpackb(data, raw=True)` for byte strings.
affects: msgpack >= 1.0 (implicitly affects msgpack-types users)
breakingThe `encoding` option for `msgpack.Packer` and `msgpack.Unpacker` was removed in `msgpack 1.0`. UTF-8 is now always used for string encoding and decoding when `raw=False`.fixRemove the `encoding` parameter from `Packer` and `Unpacker` calls. Ensure your string data is UTF-8 compatible when `raw=False` is used, or handle raw bytes explicitly with `raw=True`.
affects: msgpack >= 1.0 (implicitly affects msgpack-types users)
gotchaType stubs only provide static analysis; they do not alter runtime behavior. Installing `msgpack-types` without `msgpack` will not provide MessagePack serialization functionality at runtime, only type hints during development.fixAlways install `msgpack` alongside `msgpack-types` if you intend to run the code. `pip install msgpack msgpack-types`.
affects: All versions
gotchaPrior to `msgpack 1.0`, `use_bin_type=True` was not the default for `Packer`, meaning `bytes` objects might have been encoded as 'raw' types instead of the 'bin' type specified in MessagePack spec 2.0. This can lead to compatibility issues with newer decoders.fixFor compatibility with modern MessagePack implementations, always explicitly set `use_bin_type=True` in `msgpack.packb` and `msgpack.Packer` for `msgpack` versions older than 1.0, and be aware that `msgpack 1.0` and above default this to `True`.
affects: msgpack < 1.0 (implicitly affects msgpack-types users)
gotchaThe `strict_map_key` option in `msgpack.Unpacker` defaults to `True` in `msgpack 1.0` to mitigate hash DoS attacks. If your MessagePack data contains map keys that are not `bytes` or `str` (e.g., integers as keys), unpacking will fail unless `strict_map_key=False` is set.fixIf you need to unpack maps with non-string/non-bytes keys, explicitly pass `strict_map_key=False` to `msgpack.unpackb` or the `msgpack.Unpacker` constructor. Exercise caution when doing so with untrusted data.
affects: msgpack >= 1.0 (implicitly affects msgpack-types users)
Upgrade
Version history
0.8.0latest on PyPI · released Jun 29, 2026
Audit
Dependencies
msgpackrequiredmsgpack-types provides type stubs for the msgpack library; msgpack itself must be installed for runtime execution.