marshmallow

library4.2.3pypypi✓ verified 49d ago

Marshmallow is a lightweight library for converting complex datatypes to and from native Python datatypes. The current version is 4.2.3, released on March 28, 2026. It follows a regular release cadence, with updates approximately every few months.

serialization

pip install marshmallow

github ↗package ↗changelog ↗

Install & Compatibility

Where this runs

tested against v4.3.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

musl

py 3.10–3.925 runs

installs and imports cleanly · install 0.0s · import 0.552s · 18.7MB

glibc

py 3.10–3.925 runs

installs and imports cleanly · install 1.6s · import 0.527s · 19MB

16MB installed

● package 16MB

Code

Verified usage

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

Schema

✓ from marshmallow import Schema

Ensure correct import path to avoid ImportError.

fields

✓ from marshmallow import fields

Import fields from marshmallow to access various field types.

A simple example demonstrating how to define a schema and load data using Marshmallow.

from marshmallow import Schema, fields class UserSchema(Schema): name = fields.Str() email = fields.Email() created_at = fields.DateTime() user_data = { 'name': 'Monty', 'email': 'monty@python.org', 'created_at': '2014-08-17T14:54:16.049594+00:00' } schema = UserSchema() result = schema.load(user_data) print(result)

Debug

Known issues

breakingIn Marshmallow 4.x, the 'load' method now returns a dictionary instead of an OrderedDict by default. To maintain the previous behavior, set the 'ordered' option to True in the schema's Meta class.

fix

Add 'ordered = True' in the Meta class of your schema.

affects: 4.x

gotchaThe 'load' method in Marshmallow 4.x raises a ValidationError if it encounters unknown fields by default. To change this behavior, set the 'unknown' option in the schema's Meta class.

fix

Add 'unknown = INCLUDE' in the Meta class of your schema to include unknown fields.

affects: 4.x

Errors

Common errors & fixes

marshmallow.exceptions.ValidationError: {'field_name': ['Unknown field.']}

This error occurs when the input data contains fields that are not defined in the Marshmallow schema.

fix

To fix this, either define the 'unknown' option in your Schema's `Meta` class to `EXCLUDE` or `INCLUDE`, or ensure your input data only contains fields explicitly defined in the schema.

marshmallow.exceptions.ValidationError: {'field_name': ['Missing data for required field.']}

This error indicates that a required field, explicitly marked with `required=True` in your Marshmallow schema, was not provided in the input data during deserialization (`load` method).

fix

Ensure that all fields marked as `required=True` in your schema are present in the data being loaded.

TypeError: Object of type X is not JSON serializable

This error often occurs when trying to `jsonify` or directly JSON-encode a Python object (like a SQLAlchemy model instance or a `datetime` object) that Python's default `json` module or a framework's `jsonify` function doesn't know how to convert. Marshmallow's role is to serialize these into JSON-serializable types, but if the output of `schema.dump()` is not used or if non-serializable objects are passed directly to `jsonify` before Marshmallow processes them, this error will appear.

fix

Ensure you are using your Marshmallow schema's `.dump()` method to serialize complex Python objects into a dictionary of JSON-serializable types (like strings, numbers, booleans, lists, and dicts) before attempting to JSON-encode them with `jsonify` or `json.dumps()`. Alternatively, configure custom JSON encoders for specific types if not using Marshmallow for that particular object.

TypeError: 'type' object is not subscriptable

This error typically arises in Marshmallow when attempting to define a nested schema within a `fields.List` using `fields.List(MySchema)` instead of `fields.List(fields.Nested(MySchema))`. The `fields.List` expects a Field instance, and `fields.Nested` creates that instance from a Schema class.

fix

When defining a list of nested objects in a Marshmallow schema, wrap the nested Schema class with `fields.Nested()`. For example, use `my_list_field = fields.List(fields.Nested(MyNestedSchema))`.

Upgrade

Version history

4.3.0latest on PyPI

Audit

Dependencies

python-dateutiloptionalRecommended for robust datetime deserialization

Agent activity

17 hits · last 30 days

node

seranking-bot

Amazon

ahrefsbot

googlebot

Resources

githubhttps://github.com/marshmallow-code/marshmallow ↗

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

changeloghttps://marshmallow.readthedocs.io/en/latest/changelog.html ↗