Install & Compatibility
Where this runs
tested against v8.7.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.634s · 19.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.9s · import 0.630s · 20MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
fields
✓ from webargs import fields
✗ from marshmallow import fields
While webargs re-exports marshmallow.fields, it's best practice to import directly from webargs for consistency within the library's context.
use_args
✓ from webargs.flaskparser import use_args
Import path varies by framework (e.g., `webargs.djangoparser`, `webargs.aiohttpparser`).
Arg
✓ from webargs import fields
✗ from webargs import Arg
The `Arg` class was used in older versions (<=2.x). As of webargs 3.x, `marshmallow.fields.Field` classes (re-exported by `webargs.fields`) are used.
dict2schema
✓ from marshmallow import Schema
✗ from webargs import dict2schema
The `dict2schema` helper was removed in webargs 7.x. Use `marshmallow.Schema.from_dict` instead.
This Flask example demonstrates how to use the `use_args` decorator to parse and validate a 'name' query parameter. It uses `fields.Str` from `webargs` (which re-exports `marshmallow.fields`) to define the expected argument.
from flask import Flask
from webargs import fields
from webargs.flaskparser import use_args
app = Flask(__name__)
@app.route("/")
@use_args({"name": fields.Str(required=True)}, location="query")
def index(args):
return "Hello " + args["name"]
if __name__ == "__main__":
# To run: python your_app.py
# Then try: curl "http://127.0.0.1:5000/?name=World"
app.run(debug=True)
Debug
Known issues
breakingwebargs 7.x dropped support for Marshmallow 2. Ensure your project is using Marshmallow 3.x or later.fixUpgrade Marshmallow to version 3.x or higher: `pip install -U marshmallow>=3.0.0`.
affects: >=7.0.0
breakingThe `dict2schema` helper function was removed in webargs 7.x.fixReplace `webargs.dict2schema` with `marshmallow.Schema.from_dict`.
affects: >=7.0.0
breakingThe default behavior of the `unknown` parameter changed in webargs 8.x for `json`, `form`, and `json_or_form` locations. It now defaults to `None` instead of `RAISE` if not explicitly set. This means unknown fields might be silently ignored rather than raising an error.fixExplicitly set `unknown=marshmallow.RAISE` in your schema or `use_args`/`use_kwargs` decorator if you require strict validation against unknown fields in these locations. Example: `@use_args(MySchema(unknown=RAISE))`.
affects: >=8.0.0
breakingwebargs 7.x dropped support for Python 3.5 and webapp2.fixUpgrade your Python environment to 3.9 or higher. If using webapp2, migrate to a supported framework.
affects: >=7.0.0
gotchaWhen integrating with Flask-RESTful, webargs' default error handling may return HTTP 500 errors for validation failures instead of JSON-formatted errors.fixRegister a custom error handler using the parser's `@parser.error_handler` decorator to properly format validation errors as JSON. See `webargs` documentation on 'Error Handling' for details.
affects: All versions with Flask-RESTful
Upgrade
Version history
8.7.1latest on PyPI · released Oct 29, 2025
Audit
Dependencies
marshmallowrequiredCore dependency for schema definition and validation.