{"id":4011,"library":"flask-marshmallow","title":"Flask-Marshmallow","description":"Flask-Marshmallow is a thin integration layer for Flask, a Python web framework, and Marshmallow, an object serialization/deserialization library. It enhances Marshmallow with features like URL and Hyperlinks fields for HATEOAS-ready APIs and offers optional integration with Flask-SQLAlchemy. The current version is 1.4.0, and it follows a release cadence tied to Flask and Marshmallow updates.","status":"active","version":"1.4.0","language":"en","source_language":"en","source_url":"https://github.com/marshmallow-code/flask-marshmallow","tags":["flask","marshmallow","serialization","deserialization","api","rest","orm","sqlalchemy"],"install":[{"cmd":"pip install flask-marshmallow","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core web framework integration.","package":"flask","optional":false},{"reason":"Core serialization/deserialization library.","package":"marshmallow","optional":false},{"reason":"Optional integration for SQLAlchemy ORM.","package":"flask-sqlalchemy","optional":true},{"reason":"Optional integration for SQLAlchemy ORM schema generation.","package":"marshmallow-sqlalchemy","optional":true}],"imports":[{"symbol":"Marshmallow","correct":"from flask_marshmallow import Marshmallow"},{"note":"ModelSchema and TableSchema were removed in v0.12.0; use SQLAlchemyAutoSchema or SQLAlchemySchema instead.","wrong":"from flask_marshmallow import ModelSchema","symbol":"SQLAlchemyAutoSchema","correct":"from flask_marshmallow.sqla import SQLAlchemyAutoSchema"}],"quickstart":{"code":"from flask import Flask\nfrom flask_marshmallow import Marshmallow\n\napp = Flask(__name__)\nma = Marshmallow(app)\n\nclass User:\n    def __init__(self, id, name, email):\n        self.id = id\n        self.name = name\n        self.email = email\n\n    @classmethod\n    def get(cls, id):\n        # Simulate fetching a user from a DB\n        if id == 1:\n            return cls(1, 'Alice', 'alice@example.com')\n        return None\n\n    @classmethod\n    def all(cls):\n        # Simulate fetching all users\n        return [cls(1, 'Alice', 'alice@example.com'), cls(2, 'Bob', 'bob@example.com')]\n\nclass UserSchema(ma.Schema):\n    id = ma.Int(dump_only=True)\n    name = ma.Str(required=True)\n    email = ma.Email(required=True)\n    _links = ma.Hyperlinks({\n        \"self\": ma.URLFor(\"user_detail\", values=dict(id=\"<id>\")),\n        \"collection\": ma.URLFor(\"users\")\n    })\n\nuser_schema = UserSchema()\nusers_schema = UserSchema(many=True)\n\n@app.route(\"/api/users/\")\ndef users():\n    all_users = User.all()\n    return users_schema.dump(all_users)\n\n@app.route(\"/api/users/<int:id>\")\ndef user_detail(id):\n    user = User.get(id)\n    if user:\n        return user_schema.dump(user)\n    return {\"message\": \"User not found\"}, 404\n\nif __name__ == \"__main__\":\n    with app.test_request_context():\n        # Example usage in a test context\n        print(users())\n        print(user_detail(1))\n        print(user_detail(99))\n","lang":"python","description":"This quickstart initializes a Flask app and Flask-Marshmallow, defines a simple User class and a corresponding UserSchema. It then demonstrates how to use the schema to serialize single and multiple User objects through Flask routes, including hyperlinking."},"warnings":[{"fix":"Replace `ma.ModelSchema` or `ma.TableSchema` with `ma.SQLAlchemyAutoSchema` (recommended) or `ma.SQLAlchemySchema`. Ensure `marshmallow-sqlalchemy` is installed if using these. For example, `class AuthorSchema(ma.SQLAlchemyAutoSchema): class Meta: model = Author`.","message":"The `ModelSchema` and `TableSchema` classes were removed in `flask-marshmallow` v0.12.0. You must migrate to `SQLAlchemySchema` or `SQLAlchemyAutoSchema`.","severity":"breaking","affected_versions":">=0.12.0"},{"fix":"Update `ma.URLFor` calls within `ma.Hyperlinks` to use the `values` dictionary. Example: `ma.URLFor(\"user_detail\", values=dict(id=\"<id>\"))`.","message":"The syntax for defining `Hyperlinks` fields changed in `flask-marshmallow` v0.14.0. The `id=\"<id>\"` argument is no longer supported; `values=dict(id=\"<id>\")` should be used instead.","severity":"breaking","affected_versions":">=0.14.0"},{"fix":"Ensure `db = SQLAlchemy(app)` is called before `ma = Marshmallow(app)` in your application setup.","message":"When integrating with Flask-SQLAlchemy, the `SQLAlchemy` extension must be initialized before the `Marshmallow` extension.","severity":"gotcha","affected_versions":"*"},{"fix":"To disable Flask's default key sorting, set `app.config['JSON_SORT_KEYS'] = False` in your Flask application configuration. In production, consider letting `jsonify` sort keys for cacheability.","message":"Flask's `jsonify` method sorts keys by default, which can override `ordered=True` in your Marshmallow schemas. This can lead to unexpected key ordering in your JSON responses.","severity":"gotcha","affected_versions":"*"},{"fix":"Use feature detection or `importlib.metadata.version(\"flask-marshmallow\")` to get the package version.","message":"Accessing `flask_marshmallow.__version__` and `flask_marshmallow.__version_info__` attributes is deprecated.","severity":"deprecated","affected_versions":"Post 1.x (exact version for removal not specified, but good to be aware)"},{"fix":"For automatic field generation from ORM models, explicitly use `marshmallow-sqlalchemy`'s `SQLAlchemyAutoSchema`. Otherwise, define all fields explicitly in your `ma.Schema` classes.","message":"Marshmallow 3.x (a dependency of flask-marshmallow) removed implicit field creation. Schemas no longer infer fields automatically from data introspection.","severity":"gotcha","affected_versions":"Flask-Marshmallow versions requiring Marshmallow 3.x"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}