Marshmallow

4.2.3 · active · verified Wed Apr 08

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.

Common errors

```
marshmallow.exceptions.ValidationError: {'field_name': ['Unknown field.']}
```
cause 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.']}
```
cause 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
```
cause 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
```
cause 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))`.

Warnings

breaking In 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.
gotcha The '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.

Install

pip install marshmallow Install Marshmallow

Imports

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.

Quickstart

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)

view raw JSON →