Install & Compatibility
Where this runs
tested against v1.5.1 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.568s · 18.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.552s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
EnumField
✓ from marshmallow_enum import EnumField
This quickstart demonstrates how to define an `EnumField` in a Marshmallow schema. It uses `by_value=True` to specify that the enum should be serialized/deserialized by its member's value. The example shows both dumping (serializing) a Python `Enum` instance to a string and loading (deserializing) a string back into an `Enum` instance.
import enum
from marshmallow import Schema, fields
from marshmallow_enum import EnumField
class Color(enum.Enum):
RED = 'red'
GREEN = 'green'
BLUE = 'blue'
class ItemSchema(Schema):
name = fields.String(required=True)
color = EnumField(Color, by_value=True, required=True)
# Example usage:
schema = ItemSchema()
# Serialization (Python Enum to string/value)
item_obj = {'name': 'Apple', 'color': Color.RED}
serialized_data = schema.dump(item_obj)
print(f"Serialized: {serialized_data}")
# Expected: {'name': 'Apple', 'color': 'red'}
# Deserialization (string/value to Python Enum)
input_data = {'name': 'Sky', 'color': 'blue'}
deser_obj = schema.load(input_data)
print(f"Deserialized: {deser_obj['color'] == Color.BLUE}")
print(f"Deserialized Type: {type(deser_obj['color'])}")
# Expected: True
# Expected Type: <enum 'Color'>
Debug
Known issues
breakingThe default behavior of `EnumField` regarding `by_value` and `by_name` changed significantly in version 1.0.0. Before 1.0.0, the default was `by_value=True`. From 1.0.0 onwards, if neither `by_value` nor `by_name` is explicitly set, it attempts to load by value first, then by name.fixAlways explicitly set `by_value=True` or `by_name=True` (or use `load_by` / `dump_by`) to ensure predictable behavior, especially when upgrading or sharing schemas across different `marshmallow-enum` versions.
affects: < 1.0.0 to 1.0.0+
gotchaWhen neither `by_value` nor `by_name` is explicitly specified for `EnumField`, it will attempt to deserialize by the enum member's value first, and if that fails, then by the member's name. This implicit behavior can lead to unexpected results if your enum values or names overlap with other valid inputs.fixAlways explicitly choose `by_value=True` or `by_name=True` (or use the more granular `load_by` and `dump_by` parameters) to make your serialization logic explicit and prevent ambiguity.
affects: 1.0.0+
gotchaIf you are using `marshmallow-enum` with Marshmallow 3+, ensure you are correctly handling validation errors. Marshmallow 3 defaults to `unknown=EXCLUDE` for `Schema` which means unexpected fields are ignored, but invalid enum values will still raise validation errors. Misconfiguring `unknown` on the schema level can mask or misdirect issues.fixFor strict validation, consider setting `unknown=RAISE` on your Marshmallow schema if you want to explicitly reject unknown input fields. Always implement proper error handling for `schema.load()` to catch `ValidationError` when an invalid enum value is provided.
affects: All versions with Marshmallow 3+
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'marshmallow_enum'
The `marshmallow-enum` package has not been installed in your Python environment, or it was installed with a different name.
fixInstall the library using pip: `pip install marshmallow_enum`
ValidationError: {'field_name': ['Must be one of: ENUM_MEMBER_1, ENUM_MEMBER_2']}
The input value provided for the `EnumField` does not match any of the defined names (default) or values (if `by_value=True`) of the associated Python `enum.Enum` class members.
fixEnsure the input data for the `EnumField` is one of the valid enum member names (e.g., 'GREEN') or their corresponding values (e.g., 1) if `by_value=True` is set in `EnumField(YourEnum, by_value=True)`.
AttributeError: 'str' object has no attribute 'name'
This error typically occurs during serialization when `marshmallow-enum` expects an `enum.Enum` member object but receives a string. This can happen if the `EnumField` is incorrectly configured, especially with `by_value=True` or custom `dump_by` settings, or if the data being dumped is not in the expected enum member format.
fixEnsure that when dumping, the data corresponding to the `EnumField` is an actual `enum.Enum` member (e.g., `StopLight.red`). If you intend to dump by value, set `by_value=True` or `dump_by=EnumField.VALUE` in the `EnumField` definition to handle the string or integer values directly.
TypeError: EnumField() missing 1 required positional argument: 'enum'
The `EnumField` constructor requires the `enum.Enum` class itself as its first argument to know which enumeration to validate against.
fixPass your `enum.Enum` class to the `EnumField` constructor, for example: `my_enum_field = EnumField(MyEnumClass)`.
Using marshmallow.fields.Enum in TYPE_MAPPING for enum fields raises exception
This issue arises when attempting to use Marshmallow's native `fields.Enum` (introduced in Marshmallow 3.18) with `marshmallow-sqlalchemy`'s `ModelConverter.SQLA_TYPE_MAPPING` or when mixing `marshmallow-enum.EnumField` usage with the newer `marshmallow.fields.Enum` in a way that causes type mismatches or incompatibility, particularly with older versions of `marshmallow-sqlalchemy`.
fixFor `marshmallow-enum` (version 1.5.1), consistently use `marshmallow_enum.EnumField` for enum serialization and deserialization. If encountering issues with `marshmallow-sqlalchemy`'s automatic schema generation, explicitly define the `EnumField` in your schema rather than relying on `SQLA_TYPE_MAPPING` for enum columns. If using Marshmallow 3.18+ directly, consider using `marshmallow.fields.Enum` if `marshmallow-enum`'s specific features are not required, but be mindful of compatibility with other extensions.
Upgrade
Version history
1.5.1latest on PyPI · released Aug 21, 2019
Audit
Dependencies
marshmallowrequiredCore dependency for schema definition and serialization logic.