Install & Compatibility
Where this runs
tested against v3.1.0 · 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.920 runs
installs and imports cleanly · install 0.0s · import 1.455s · 38.6MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.9s · import 1.383s · 38MB
37MB installed
● package 37MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
APIFlask
✓ from apiflask import APIFlask
APIBlueprint
✓ from apiflask import APIBlueprint
✗ from flask import Blueprint
Use APIBlueprint for OpenAPI-enabled blueprints instead of Flask's Blueprint.
abort
✓ from apiflask import abort
✗ from flask import abort
APIFlask's abort returns JSON error responses by default, unlike Flask's.
HTTPError
✓ from apiflask import HTTPError
Schema
✓ from apiflask import Schema
For Marshmallow schemas. Fields like `String`, `Integer` are also imported from `apiflask.fields`.
BaseModel
✓ from pydantic import BaseModel
For Pydantic models, requires pydantic to be installed.
This quickstart initializes an APIFlask application, defines a simple Marshmallow schema for responses, and sets up a GET endpoint that returns a JSON message. APIFlask automatically generates OpenAPI documentation available at `/docs` by default.
from apiflask import APIFlask
from apiflask.fields import String
from apiflask.schemas import Schema
app = APIFlask(__name__, title='My Awesome API', version='1.0.0')
class MessageSchema(Schema):
message = String(required=True, example='Hello from APIFlask')
@app.get('/')
@app.output(MessageSchema)
def index():
return {'message': 'Hello from APIFlask'}
# To run: flask --app your_app_file_name run
Debug
Known issues
breakingAPIFlask 3.x refactored API key authentication. Old classes like `HTTPTokenAuth` are deprecated for API keys. Instead, use `APIKeyHeaderAuth`, `APIKeyCookieAuth`, or `APIKeyQueryAuth` based on the key's location.fixUpdate your authentication logic to import and use the new `security.APIKey*Auth` classes from `apiflask.security` and configure them appropriately.
affects: 3.0.0 and later
breakingAPIFlask 3.x dropped official support for Python 3.8 and PyPy 3.10. While it might still work, new features and fixes are not guaranteed for these versions.fixUpgrade your Python environment to Python 3.9 or newer.
affects: 3.0.0 and later
breakingIn APIFlask 2.x, data passed via the `@app.input()` decorator is now injected into the view function as a keyword argument named `{location}_data` (e.g., `json_data`, `query_data`).fixAdjust your view function signatures to accept the input data as a keyword argument, e.g., `def create_pet(json_data):`.
affects: 2.0.0 and later
gotchaAPIFlask's `abort()` function (`from apiflask import abort`) automatically returns a JSON error response, which differs from Flask's default `flask.abort()` behavior (which typically returns HTML).fixAlways import `abort` from `apiflask` when you intend to return structured JSON errors. Be aware that if `app.json_errors` is True (default), Flask's `flask.abort` will also return JSON error responses, but `apiflask.abort` offers more control.
affects: All versions
gotchaWhen using Pydantic models for output validation with `@app.output()`, if the data returned by your view function does not conform to the specified Pydantic model, APIFlask will raise a `500 Internal Server Error` before sending the response.fixEnsure that the data returned by your view functions strictly matches the defined Pydantic output model. Implement thorough testing of your output serialization.
affects: 3.0.0 and later (when using Pydantic)
breakingAPIFlask 1.2.0 introduced a breaking change where `apiflask.views.MethodView` must be used for class-based views instead of `flask.views.MethodView` to ensure proper OpenAPI spec generation and functionality.fixImport `MethodView` from `apiflask.views` for your class-based views, e.g., `from apiflask.views import MethodView`.
affects: 1.2.0 and later
breakingThe default status code for request validation errors changed from `400 Bad Request` to `422 Unprocessable Entity` in APIFlask 1.2.0, aligning with common API practices for semantic validation errors.fixUpdate client-side error handling to expect `422` for input validation failures.
affects: 1.2.0 and later
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'apiflask'
The `apiflask` library is not installed in the current Python environment.
fixRun `pip install apiflask` to install the library.
TypeError: The view function did not return a valid response. The return type must be a string, dict, tuple, Response instance, or WSGI callable.
Your view function returned a complex object (e.g., a custom class instance) without an `@app.output()` decorator to serialize it, or the object is not a simple dictionary/list that Flask can convert to JSON.
fixDecorate your view function with `@app.output(YourSchema)` to define how the return value should be serialized to JSON. If returning a non-dict, ensure it's explicitly handled or convertible.
werkzeug.exceptions.UnprocessableEntity: 422 Unprocessable Entity
This error (or similar `ValidationError` from Marshmallow/Pydantic) indicates that the request payload did not conform to the schema defined in the `@app.input()` decorator.
fixCheck the API documentation for the expected input schema and ensure your request body or query parameters match it. The error response details will typically provide specifics on validation failures.
AttributeError: 'HTTPTokenAuth' object has no attribute 'verify_apikey' (or similar auth-related AttributeError)
You are likely using `HTTPTokenAuth` for API key authentication on APIFlask v3.x or later, which has been deprecated and refactored.
fixMigrate your API key authentication to use `APIKeyHeaderAuth`, `APIKeyCookieAuth`, or `APIKeyQueryAuth` from `apiflask.security`.
RuntimeError: 'APIFlask' object has no attribute 'json_errors' when trying to configure JSON error handling (or similar configuration issues)
Accessing or setting configuration variables incorrectly, or attempting to configure features that have been renamed or refactored in newer versions.
fixConsult the `APIFlask` documentation for the current version's configuration variables and their correct usage. Some settings might have moved or been replaced by `APIFlask` constructor arguments or specific decorators.
Upgrade
Version history
3.1.0latest on PyPI · released Mar 22, 2026
Audit
Dependencies
PythonrequiredRequired for execution
FlaskrequiredCore web framework dependency
marshmallowoptionalDefault data validation and serialization library
pydanticoptionalAlternative data validation and serialization library (v3.x+)