mashumaro

library3.20pypypi✓ verified 52d ago

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.

serialization

pip install mashumaro

github ↗package ↗homepage ↗

Install & Compatibility

Where this runs

tested against v3.22 · 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

musl

py 3.10–3.950 runs

installs and imports cleanly · install 0.0s · import 0.140s · 19.3MB

glibc

py 3.10–3.950 runs

installs and imports cleanly · install 1.9s · import 0.127s · 20MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

DataClassJSONMixin

✓ from mashumaro.mixins.json import DataClassJSONMixin

Primary mixin for JSON serialization/deserialization with dataclasses.

DataClassDictMixin

✓ from mashumaro import DataClassDictMixin

Core mixin for dictionary serialization/deserialization with dataclasses.

build_json_schema

✓ from mashumaro.jsonschema import build_json_schema

For generating JSON Schema from dataclasses.

Define a dataclass inheriting from `DataClassJSONMixin` to automatically gain `to_json()` and `from_json()` methods for seamless JSON serialization and deserialization.

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

Debug

Known issues

breakingIn 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.

affects: >=3.15

breakingSupport 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.

affects: >=3.15

gotchaWhen 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.

affects: <3.13.1

gotchaMashumaro 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.

affects: All

gotchaThe `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`.

affects: >=3.13

Errors

Common errors & fixes

mashumaro.exceptions.MissingField: Field "<field_name>" of type <field_type> is missing in <dataclass_name> instance

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.

mashumaro.exceptions.ExtraKeysError: Serialized dict has keys that are not defined in <dataclass_name>: <extra_keys_str>

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.

mashumaro.exceptions.UnserializableField: Field "<field_name>" of type <field_type> in <dataclass_name> is not serializable

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.

mashumaro.exceptions.ThirdPartyModuleNotFoundError: Install "<module_name>" to use it as the serialization method for the field "<field_name>" in <dataclass_name>

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.

Upgrade

Version history

3.22latest on PyPI

Audit

Dependencies

orjsonoptionalOptional dependency for faster JSON serialization/deserialization.

Agent activity

13 hits · last 30 days

seranking-bot

node

ahrefsbot

Amazon

Resources

githubhttps://github.com/Fatal1ty/mashumaro ↗

packagehttps://pypi.org/project/mashumaro/ ↗

homepagehttps://mashumaro.io ↗