Registry /
database / marshmallow-mongoengine
Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ModelSchema
✓ from marshmallow_mongoengine import ModelSchema
✗ from marshmallow_mongoengine.schema import ModelSchema
Direct import from top-level package is the intended way; the internal 'schema' module is not part of public API.
fields
✓ from marshmallow_mongoengine import fields
✗ from marshmallow_mongoengine.fields import *
Import fields as a module, not individual names, to avoid name conflicts with marshmallow's fields.
Basic example: define a MongoEngine Document and a ModelSchema, then serialize/deserialize.
import os
from mongoengine import connect, Document, StringField
from marshmallow_mongoengine import ModelSchema
# Connect to MongoDB (use environment variable for production)
connect('mydb', host=os.environ.get('MONGO_URI', 'mongodb://localhost:27017'))
# Define a MongoEngine model
class User(Document):
name = StringField(required=True)
email = StringField(required=True)
# Define a marshmallow-mongoengine schema
class UserSchema(ModelSchema):
class Meta:
model = User
# Usage
schema = UserSchema()
user_doc = User(name='Alice', email='alice@example.com')
result = schema.dump(user_doc)
print(result) # {'_id': ObjectId('...'), 'name': 'Alice', 'email': 'alice@example.com'}
# Deserialize
data, errors = schema.load({'name': 'Bob', 'email': 'bob@example.com'})
if not errors:
user = data # User() instance, not yet saved
Debug
Known issues
gotchaModelSchema dumps include '_id' field by default, which may expose internal MongoDB IDs. Exclude or rename via Meta options if not desired.fixIn Meta, add: exclude = ['_id'] or override the field with dump_only=True.
affects: all
breakingIn marshmallow 3.x, nested fields require explicit 'nested' declaration; automatic nesting from Document references may break if not properly configured.fixFor ReferenceField or ListField(ReferenceField), ensure the referenced Document has its own ModelSchema and use the 'nested' parameter explicitly in the parent schema.
affects: >=0.22.0 with marshmallow 3
deprecatedThe old top-level import 'from marshmallow_mongoengine import ModelSchema' is correct, but 'from marshmallow_mongoengine.schema' is deprecated and may be removed in future.fixAlways import from the top-level package: from marshmallow_mongoengine import ModelSchema
affects: all
gotchaModelSchema inherits marshmallow's Schema; avoid overriding 'Meta' class with non-Meta attributes like 'model' - use 'model' inside Meta.fixCorrect: class Meta: model = MyModel. Incorrect: model = MyModel outside Meta.
affects: all
Errors
Common errors & fixes
marshmallow.exceptions.RegistryError: Class with name '...' already exists
Multiple ModelSchema classes with the same name (or referencing same model) are registered in marshmallow's class registry, which is global.
fixEnsure each schema class has a unique name, or use marshmallow's `class_registry` to avoid conflicts. Alternatively, set `meta.registered = False` to bypass registry.
ModuleNotFoundError: No module named 'marshmallow_mongoengine'
Package not installed or installed in the wrong environment.
fixRun `pip install marshmallow-mongoengine` in the correct Python environment. If using virtualenv, ensure it's activated.
TypeError: 'NoneType' object is not iterable
A back-reference (reverse relation) is not properly defined or the field is missing on the referenced document.
fixDefine the reverse relation explicitly using `db_field` or `reverse_delete_rule` on the MongoEngine side, and ensure the schema includes the backref field via `nested` or `fields.List`.
Upgrade
Version history
0.31.2latest on PyPI · released Mar 14, 2023
Audit
Dependencies
marshmallowrequiredCore dependency for serialization/deserialization
mongoenginerequiredCore dependency - the ODM this library wraps
flask-marshmallowoptionalOptional integration for Flask applications