NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #689 most downloaded on PyPI
Fast and well tested serialization library
Last release 4 days ago
30 Sep 2026
Ships fairly regularly
a new release about every 3 months
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
8 years old
95 releases · first in 2018
Fixed type annotation for TOMLEncoder.encode and toml_encode return values ( #328 ) in #329 by @EliasStar
TOMLEncoder.encode and toml_encode return values (#328) in #329 by @EliasStarGeneric[...] (#332) in #335 by @Fatal1tyTypeVar when the generic is unspecialized (#349) in #350 by @Fatal1tyConfig subclasses (#354) in #355 by @Fatal1tyCodeBuilder memory leak caused by lru_cache (#364) in #365 by @Fatal1tyTypedDict aliases and inherited specializations resolve (#379) in #380 by @Fatal1tyslice type (#242, #371) in #356, #372 by @00200200, @Fatal1tyTypedDict with Typed Extra Items (#271, #378) in #352, #381 by @edgarrmondragon, @Fatal1tymemoryview type (#358) in #359, #360 by @Fatal1tyBuffer type (#360) in #361 by @Fatal1tyfrozendict type (#369) in #370 by @Fatal1tyTypeForm for APIs that accept type expressions (#366) in #367 by @Fatal1tyOne column per quarter.
Added support for using Annotated[..., JSONSchema(...)] in JSON Schema generation
Added support for recursive dataclasses in JSON Schema
lazy_compilation config value in generic dataclasses with inheritance (#319)Fixed type name for for PEP 695 types created with type keyword
type keyword (#305)Added support for recursive types in JSON Schema
Fixed support for PEP 695 types created with type keyword in JSON Schema
Improved generating JSON Schema references and titles for generic dataclasses
T (#290)NotRequired when using from __future__ import annotations (#292)field_options function (#286)Added support for custom JSON Schema instance formats defined by users
Improved Union and basic types deserialization ( #256 ), highlighted changes:
Union and basic types deserialization (#256), highlighted changes:
int | float or float | int value can now be passed through without coercion and losing precisionstr value will be guaranteed to be a string version of the input value (#42)bool value will be guaranteed to be a boolean using standard truth testing procedure for the input valueNoneType will be guaranteed to be None regardless of the input valueDocstringDescriptionPlugin to use a docstring as a description (#222)Union types (#206)Fixed DeprecationWarning introduced in Python 3.13
Fixed type annotation for the result of to_json method in DataClassORJSONMixin
Added support for Python 3.13 (#208, #209)
MappingProxyType (#218)forbid_extra_keys config option to reject extra keys on deserialization (#197, #198)Alias(...) annotation (#214), see updated documentationomit_default didn't work for Enum with basic types mixed in (#204)RecursionError when annotated SerializationStrategy was used as a field serialization strategy (#219)Added support for associating multiple tags with a single variant by returning a list of tags from variant_tagger_fn
variant_tagger_fn (#184)ForwardRef in JSON Schema generation (#187)IntFlag when omit_default is enabled (#188)serialization_strategy config optionAdded "codecs" feature to separate data models from serialization and work with top-level lists, dataclasses without mixins etc. (#108, #69), see upda
allow_deserialization_not_by_alias config option to allow deserialization by both alias and field name, see documentation (https://github.com/Fatal1ty/mashumaro/pull/175)UnserializableDataError for generic serializable types and generic serialization strategies with postponed evaluation of annotations (#177)ValueError was not thrown if invalid value type was passed to from_* methodserialize_by_alias dialect optionnamedtuple_as_dict dialect optionAdded new sort_keys config option to sort keys on serialization, see documentation
sort_keys config option to sort keys on serialization, see documentation (#157)omit_default config and dialect options to exclude values equal to defaults on serialization, see documentation (#161)variant_tagger_fn discriminator parameter to allow discrimination based on a key that is not part of the model, see documentation (#135)no_copy_collections dialect option to avoid collection data types copying, see documentation (#163)LiteralString (#166)ForwardRef types (#144)SerializableType and GenericSerializableType subclasses (#156)flake8 to ruff (#150)Fixed handling of collections of annotated with unhashable metadata types on python < 3.9
Added support for inner dataclasses without mashumaro mixins
default_factory by JSON Schema generator (#114)additionalProperties in JSON Schema (#123)Annotated type with unhashable metadata (#133)Fixed issues introduced in 3.8 when dataclass instantiation produced TypeError if one of the fields was overridden (#118) or post-deserialize hook was
TypeError if one of the fields was overridden (#118) or post-deserialize hook was used (#120)Added new `Discriminator` type for discriminated unions and subclasses support, see documentation
Discriminator type for discriminated unions and subclasses support, see documentation (#106)to_* methods to the hooks, see documentation (#110)Annotated are now different from unenclosed ones in serialization_strategy, see documentation (#115)lazy_compilation config option that can reduce import time and speed up deserialization, see documentationFinal types (#107)Literal on Python 3.9.0 (#103)SerializableType when TypeVars were mixed with ordinary types in _serialize / _deserialize annotationsdataclasses.KW_ONLY resulted in UnserializableDataErrorfrom_dict method could result in unhandled exceptionsAdded "omit" serialization engine to skip the field during serialization
"omit" serialization engine to skip the field during serializationref_prefix parameter to build_json_schema and JSONSchemaBuilder to change reference prefixAdded JSON Schema generation functionality 🎉 (see documentation)
Added possibility to define a generic serialization method for a generic type by registering a method for its origin type
SerializationStrategy (details)SerializationStrategy methods by optional use_annotations=True (details)__class_getitem__ methods will now be treated as generic types according to PEP 560Added support for typing.DefaultDict / collections.defaultdict
typing.DefaultDict / collections.defaultdictTypedDict and generic NamedTupleFixed UnresolvedTypeReferenceErrorwhen postponed annotations were used and parent generic dataclass was defined in different module. See https://githu
UnresolvedTypeReferenceErrorwhen postponed annotations were used and parent generic dataclass was defined in different module. See https://github.com/Fatal1ty/mashumaro/issues/90.Added ability to use annotations inside SerializableType to simplify dealing with generic types (see updated documentation)
SerializableType to simplify dealing with generic types (see updated documentation)TypeVarTuple and Unpack from PEP 646Tuple[()] on python 3.11Tuple[T, ...] from "Tuple[T, Ellipsis]" to "Tuple[T, ...]"Added skipping None value fields on serialization to TOML format. See https://github.com/Fatal1ty/mashumaro/issues/85.
None value fields on serialization to TOML format. See https://github.com/Fatal1ty/mashumaro/issues/85.omit_none config optionomit_none dialect optionNone values to fields that can't be None according to their typeFixed using compiled mixins with inheritance. See https://github.com/Fatal1ty/mashumaro/issues/87.
Added support for typing.Self and typing_extensions.Self
typing.Self and typing_extensions.Selffrom_dict and to_dict, methods in other mixins can also be compiled nowDataClassMessagePackMixin:
ADD_DIALECT_SUPPORT config option when using DataClassMessagePackMixinfrom_msgpack and to_msgpack are now compiledDataClassORJSONMixin to use a third-party orjson library that will handle supported data types by itself
orjson_options config option to change default options passing to orjson.dumps methodto_jsonb and to_json have orjson_options keyword argument to override the default optionsDataClassTOMLMixinFixed using fields with init=False — they are skipped during deserialization now. See https://github.com/Fatal1ty/mashumaro/issues/82.
init=False — they are skipped during deserialization now. See https://github.com/Fatal1ty/mashumaro/issues/82.Fixed using dialects for DataClassMessagePackMixin. See https://github.com/Fatal1ty/mashumaro/issues/76.
DataClassMessagePackMixin. See https://github.com/Fatal1ty/mashumaro/issues/76.Fixed using dialects with inheritance. See https://github.com/Fatal1ty/mashumaro/issues/78.
Fixed using Optional in tuples, named tuples and typed dicts. See https://github.com/Fatal1ty/mashumaro/issues/73.
typing_extensions.OrderedDict on Python<3.7.2.
typing.NewTypetyping.Literaltyping_extensions.Literaltyping.Annotatedtyping_extensions.Annotatedzoneinfo.ZoneInfotyping_extensions.OrderedDict on Python<3.7.2.SerializableType generic classes.pass_through object that can be used in serialization_strategy and serialize / deserialize options.msgpack, pyyaml dependencies to extras_require (https://github.com/Fatal1ty/mashumaro/issues/7).DataClassJSONMixin, DataClassMessagePackMixin, DataClassYAMLMixin to mashumaro.mixins.* subpackages.use_bytes, use_enum, use_datetime parameters from DataClassDictMixin methods.to_*, from_* methods of the serialization mixins in order to pass keyword arguments to underlying to_dict, from_dict methods.You can find migration guide here: https://github.com/Fatal1ty/mashumaro/blob/master/docs/2to3.md.
Fixed that Union[None, X] with None on the first place wasn't treated as Optional[X].
Union[None, X] with None on the first place wasn't treated as Optional[X].Union[X, T] where T was resolved to None wasn't treated as Optional[X].None as the field type (it's considered equivalent to NoneType).NoneType to None in Unions for convenience. In the previous versions you could see Union[int, str, NoneType] instead of Union[int, str, None] if the field was declared as Union[int, str, None].Fixed using nested classes with future annotations import. See https://github.com/Fatal1ty/mashumaro/issues/62.
Fixed type hints for to_msgpack and from_msgpack methods. See https://github.com/Fatal1ty/mashumaro/issues/63.
to_msgpack and from_msgpack methods. See https://github.com/Fatal1ty/mashumaro/issues/63.serialization_strategy config option in a generic dataclass.Fixed installing with third-party tool pdistx. See https://github.com/Fatal1ty/mashumaro/issues/60.
Union and TypeVar types. See https://github.com/Fatal1ty/mashumaro/issues/61.by_alias argument of to_dict method when using serialize_by_alias config option. In the previous versions by_alias argument had a default valueFalse regardless of whether serialize_by_alias config options was used. Now it could be True:@dataclass
class MyClass(DataClassDictMixin):
x: int
class Config(BaseConfig):
aliases = {"x": "x_alias"}
serialize_by_alias = True
code_generation_options = [TO_DICT_ADD_BY_ALIAS_FLAG]
print(MyClass(x=1).to_dict()) # {'x_alias': 1}
print(MyClass(x=1).to_dict(by_alias=False)) # {x': 1}
Added support for PEP 563 postponed evaluation of annotations. See here for details.
as_dict and as_list serialization and deserialization enginesnamedtuple_as_dict config optionAdded support for typed NamedTuple and untyped namedtuple
TypedDictNamedTuple and untyped namedtupleTuple serialization and deserialization. Before 2.8 all values of tuples were deserialized as if they were values of the first type, no matter how many values the tuple was supposed to take. Now the following types are handled correctly: Tuple[int], Tuple[int, ...], Tuple[int, str], Tuple[()], Tuple.Added extended support for user-defined generic types. See here for details.
Fixed serialization of Optional types inside collections
Optional types inside collections (https://github.com/Fatal1ty/mashumaro/issues/54)Fixed serialization of np.ndarray and other third-party collection types
np.ndarray and other third-party collection types (https://github.com/Fatal1ty/mashumaro/issues/53)Fixed broken type_name for Optional types
type_name for Optional typesfrom_dict method when using TypeVar with a bound parameterFixed broken MissingField and InvalidFieldValue exceptions with shortened generic type names
MissingField and InvalidFieldValue exceptions with shortened generic type namesAdded support for TypeVar types. It works like Union under the hood and both constraints and upper bound can be used to specify a variation of types.
TypeVar types. It works like Union under the hood and both constraints and upper bound can be used to specify a variation of types. Similarly to Union it's recommended to place more complex variant types at first place like TypeVar("T", Dict[int, int], List[int]) not TypeVar("T", List[int], Dict[int, int]).List instead of List[Any] or Dict instead of Dict[Any, Any].int instead of builtins.int or List instead of typing.List.Fixed broken serialization of data classes that also inherit another supported serializable class like MutableMapping. See https://github.com/Fatal1ty
MutableMapping. See https://github.com/Fatal1ty/mashumaro/issues/48.Union type fields in some cases.Fixed calling to_dict method of a class that doesn't have `omit_none` and `by_alias` keyword arguments added in case it has a field of the type that h
to_dict method of a class that doesn't have omit_none and by_alias keyword arguments added in case it has a field of the type that has these arguments added:@dataclass
class A(DataClassDictMixin):
x: Optional[int] = None
class Config(BaseConfig):
aliases = {"x": "x_alias"}
code_generation_options = [
TO_DICT_ADD_OMIT_NONE_FLAG,
TO_DICT_ADD_BY_ALIAS_FLAG,
]
@dataclass
class B(DataClassDictMixin):
a: Optional[A] = None
# This caused an exception NameError: name 'omit_none' is not defined
print(B(a=A(1)).to_dict())
Improved deserialization speed by removing import statements from generated code.
SerializableType data classes.UnserializableField for data classes without DataClassDictMixin parent.ThirdPartyModuleNotFoundError, that is raised in case you use pendulum or ciso8601 as the deserialization method, but the corresponding package isn't installed.Added support for `__slots__` attribute. See https://github.com/Fatal1ty/mashumaro/issues/47.
__slots__ attribute. See https://github.com/Fatal1ty/mashumaro/issues/47.new `serialize_by_alias` config option
alias field optionaliases config optionserialize_by_alias config optionTO_DICT_ADD_BY_ALIAS_FLAG code generation optionFixed passing a value to serialize method of SerializationStrategy registered in Config: https://github.com/Fatal1ty/mashumaro/issues/44
serialize method of SerializationStrategy registered in Config: https://github.com/Fatal1ty/mashumaro/issues/44Fixed loading typing information for mypy https://github.com/Fatal1ty/mashumaro/pull/43
SerializationStrategy is now a field option (backward incompatible change). See here for details.
collections.OrderedDict (3.7+) and collections.Counter typesserialize and deserialize field metadata options in Union and Optional typesSerializationStrategy is now a field option (backward incompatible change). See here for details.Config class. See here for details.Added support for Union types. It's recommended to place more complex variant types at first place like Union[Dict[int, int], List[int]] not Union[Lis
Union types. It's recommended to place more complex variant types at first place like Union[Dict[int, int], List[int]] not Union[List[int], Dict[int, int]]. When optional type validation is implemented it will be possible not to follow this rule.serialize and deserialize options for any third-party types and SerializableType classes if you need it for some reason.Added support for MyEnum(str, Enum): https://github.com/Fatal1ty/mashumaro/pull/33
@dataclass
class A(DataClassDictMixin):
@dataclass
class B(DataClassDictMixin):
b: int
a: int
b: B
print(A.from_dict({'a': 1, 'b': {'b': 2}}))
Support for hooks declared in superclasses
class Counter:
deserialize = 0
serialize = 0
@classmethod
def __pre_deserialize__(cls, d):
Counter.deserialize += 1
return d
def __pre_serialize__(self):
Counter.serialize += 1
return self
@dataclass
class Derived(Counter, DataClassDictMixin):
a: int
obj = Derived.from_dict({"a": 1})
obj.to_dict()
print(Counter.deserialize) # 1
print(Counter.serialize) # 1
Added support for ipaddress types
ipaddress types (https://github.com/Fatal1ty/mashumaro/pull/29)Added serialization hooks https://github.com/Fatal1ty/mashumaro#serialization-hooks
@dataclass
class User(DataClassJSONMixin):
name: str
password: str
is_deserialized: bool = False
counter: ClassVar[int] = 0
@classmethod
def __pre_deserialize__(cls, d: Dict[Any, Any]) -> Dict[Any, Any]:
return {k.lower(): v for k, v in d.items()}
@classmethod
def __post_deserialize__(cls, obj: "User") -> "User":
obj.is_deserialized = True
return obj
def __pre_serialize__(self) -> "User":
self.counter += 1
return self
def __post_serialize__(self, d: Dict[Any, Any]) -> Dict[Any, Any]:
d.pop("password")
return d
user = User.from_json('{"NAME": "Name", "PASSWORD": "secret"}')
print(user) # User(name='Name', password='secret', is_deserialized=True)
print(user.to_json()) # {"name": "Name", "is_deserialized": true}
print(user.counter) # 1
Added support for serialize option:
serialize option:@dataclass
class A(DataClassDictMixin):
dt: datetime = field(
metadata={
"serialize": lambda v: v.strftime('%Y-%m-%d %H:%M:%S')
}
)
Fixed weird TypeError exception that was thrown instead of MissingField in case when field doesn't have default argument
TypeError exception that was thrown instead of MissingField in case when field doesn't have default argumentmetadata argument. See here for details.Your coding agent can read these notes before it upgrades. Set up the MCP server →