mashumaro
raw JSON → 3.20 verified Tue May 12 auth: no python install: verified
mashumaro is a fast and well-tested serialization library built on top of Python dataclasses. It provides efficient conversion of dataclass instances to and from various formats like JSON, YAML, TOML, MessagePack, and plain dictionaries. It is actively maintained with frequent releases, currently at version 3.20.
pip install mashumaro Common errors
error mashumaro.exceptions.MissingField: Field "<field_name>" of type <field_type> is missing in <dataclass_name> instance ↓
cause This error occurs during deserialization when the input data (e.g., a dictionary or JSON string) lacks a required field defined in the target dataclass.
fix
Ensure that the input data for deserialization contains all non-optional fields required by the dataclass. For example, if 'name: str' is a field, the input dictionary must have a 'name' key.
error mashumaro.exceptions.ExtraKeysError: Serialized dict has keys that are not defined in <dataclass_name>: <extra_keys_str> ↓
cause This error happens during deserialization if the input dictionary contains keys that are not defined as fields in the dataclass, and the `forbid_extra_keys` configuration option is enabled.
fix
Either ensure the input dictionary only contains keys corresponding to dataclass fields, or set
forbid_extra_keys = False in your dataclass's Config or code_generation_options during deserialization if you want to ignore extra keys. error mashumaro.exceptions.UnserializableField: Field "<field_name>" of type <field_type> in <dataclass_name> is not serializable ↓
cause This error indicates that Mashumaro does not know how to serialize or deserialize the type of a specific field within your dataclass.
fix
Define a custom serialization strategy for the field's type using
mashumaro.types.SerializationStrategy or mashumaro.types.SerializableType, or ensure the field's type is one of Mashumaro's natively supported types or a dataclass itself. error mashumaro.exceptions.ThirdPartyModuleNotFoundError: Install "<module_name>" to use it as the serialization method for the field "<field_name>" in <dataclass_name> ↓
cause This error occurs when you attempt to use a Mashumaro mixin or feature that relies on an optional third-party library (e.g., `orjson` for `DataClassORJSONMixin`, `pyyaml` for `DataClassYAMLMixin`) that has not been installed.
fix
Install the required optional dependency using pip, often with Mashumaro's extras, like
pip install mashumaro[orjson] for ORJSON support or pip install mashumaro[yaml] for YAML support. Warnings
breaking In v3.15, deserialization behavior for Unions with `int | float`, `str`, `bool`, and `NoneType` changed. Values are now passed through without coercion for numeric types (if they match), `str` is guaranteed a string version, `bool` uses standard truth testing, and `NoneType` is guaranteed `None`. This can lead to different deserialization results if your application relied on previous implicit coercions or conversions. ↓
fix Review deserialization logic for fields using `Union` or basic types to align with the new, more precise behavior. Explicitly define serialization/deserialization strategies if specific coercions are required.
breaking Support for Python 3.8 was dropped in mashumaro v3.15. Projects using Python 3.8 must pin mashumaro to a version prior to 3.15. ↓
fix Upgrade Python to 3.9 or higher, or pin `mashumaro<3.15` in your project dependencies.
gotcha When using `DataClassORJSONMixin`, prior to v3.13.1, the `to_json` method's type annotation incorrectly returned `str`. This was fixed in v3.13.1 to return `str` or `bytes` correctly depending on `orjson_options`, affecting static analysis and potentially runtime if strict type checks are in place. ↓
fix Upgrade to mashumaro v3.13.1 or later to get correct type annotations for `DataClassORJSONMixin.to_json`. Consider using `to_jsonb()` if byte output is desired for performance.
gotcha Mashumaro offers two primary approaches for serialization: Mixins (e.g., `DataClassJSONMixin`) for dataclass models, and Codecs (e.g., `JSONDecoder`, `JSONEncoder`) for converting arbitrary Python types or top-level collections. Choosing the wrong approach can lead to more verbose code or lack of desired functionality. ↓
fix Use Mixins when your root data structure is a dataclass. Use Codecs when you need to serialize/deserialize arbitrary types (like a `List[datetime]`) or top-level collections that are not directly represented by a single dataclass.
gotcha The `forbid_extra_keys` configuration option (introduced in v3.13) and `Alias(...)` annotation for field aliasing (also v3.13) offer powerful control but can lead to deserialization failures if not configured correctly. Extra keys will be rejected if `forbid_extra_keys` is set to `True`, and fields might not deserialize by their original name if `Alias` is used without `allow_deserialization_not_by_alias`. ↓
fix Be explicit with `forbid_extra_keys` in your `Config` if you want strict validation. If using `Alias(...)` for field aliasing and require deserialization by both alias and original field name, set `allow_deserialization_not_by_alias=True` in your dataclass `Config`.
Install
pip install mashumaro[orjson] Install compatibility verified last tested: 2026-05-12
python os / libc variant status wheel install import disk
3.10 alpine (musl) mashumaro wheel - 0.12s 18.9M
3.10 alpine (musl) mashumaro - - 0.13s 18.9M
3.10 alpine (musl) orjson wheel - 0.11s 19.3M
3.10 alpine (musl) orjson - - 0.13s 19.3M
3.10 slim (glibc) mashumaro wheel 1.6s 0.09s 19M
3.10 slim (glibc) mashumaro - - 0.08s 19M
3.10 slim (glibc) orjson wheel 2.2s 0.09s 20M
3.10 slim (glibc) orjson - - 0.08s 20M
3.11 alpine (musl) mashumaro wheel - 0.17s 21.0M
3.11 alpine (musl) mashumaro - - 0.20s 21.0M
3.11 alpine (musl) orjson wheel - 0.17s 21.4M
3.11 alpine (musl) orjson - - 0.20s 21.4M
3.11 slim (glibc) mashumaro wheel 1.7s 0.16s 21M
3.11 slim (glibc) mashumaro - - 0.15s 21M
3.11 slim (glibc) orjson wheel 2.0s 0.15s 22M
3.11 slim (glibc) orjson - - 0.14s 22M
3.12 alpine (musl) mashumaro wheel - 0.15s 12.8M
3.12 alpine (musl) mashumaro - - 0.15s 12.8M
3.12 alpine (musl) orjson wheel - 0.14s 13.2M
3.12 alpine (musl) orjson - - 0.15s 13.2M
3.12 slim (glibc) mashumaro wheel 1.5s 0.15s 13M
3.12 slim (glibc) mashumaro - - 0.15s 13M
3.12 slim (glibc) orjson wheel 1.8s 0.15s 14M
3.12 slim (glibc) orjson - - 0.15s 14M
3.13 alpine (musl) mashumaro wheel - 0.14s 12.5M
3.13 alpine (musl) mashumaro - - 0.14s 12.4M
3.13 alpine (musl) orjson wheel - 0.13s 12.9M
3.13 alpine (musl) orjson - - 0.14s 12.8M
3.13 slim (glibc) mashumaro wheel 1.6s 0.14s 13M
3.13 slim (glibc) mashumaro - - 0.15s 13M
3.13 slim (glibc) orjson wheel 1.8s 0.14s 13M
3.13 slim (glibc) orjson - - 0.14s 13M
3.9 alpine (musl) mashumaro wheel - 0.11s 18.4M
3.9 alpine (musl) mashumaro - - 0.12s 18.4M
3.9 alpine (musl) orjson wheel - 0.11s 18.7M
3.9 alpine (musl) orjson - - 0.12s 18.7M
3.9 slim (glibc) mashumaro wheel 1.9s 0.10s 19M
3.9 slim (glibc) mashumaro - - 0.10s 19M
3.9 slim (glibc) orjson wheel 2.5s 0.10s 19M
3.9 slim (glibc) orjson - - 0.10s 19M
Imports
- DataClassJSONMixin
from mashumaro.mixins.json import DataClassJSONMixin - DataClassDictMixin
from mashumaro import DataClassDictMixin - build_json_schema
from mashumaro.jsonschema import build_json_schema
Quickstart last tested: 2026-04-24
from dataclasses import dataclass
from mashumaro.mixins.json import DataClassJSONMixin
@dataclass
class User(DataClassJSONMixin):
name: str
email: str
age: int
# Serialize to JSON
user = User(name='Alice', email='alice@example.com', age=30)
json_str = user.to_json()
print(f"Serialized: {json_str}")
# Deserialize from JSON
restored_user = User.from_json(json_str)
print(f"Deserialized: {restored_user}")
assert restored_user == user