pallets/flask · error · RuntimeError

Install Flask with the 'async' extra in order to use async…

Error message

Install Flask with the 'async' extra in order to use async views.

What it means

Raised by Flask's async-to-sync bridge when asgiref is not importable. Flask supports async view functions but requires the asgiref package to wrap them for the synchronous WSGI server. Without it the runtime cannot call the coroutine.

Solutions

Install the async extra: pip install flask[async] (equivalently pip install asgiref).
Pin asgiref in requirements.txt if dependency resolution drops it.
If async is not needed, convert the view to a synchronous def and avoid the bridge entirely.

Example fix

// before
async def index(): ...
# Flask with no asgiref installed -> raises at request time
// after
pip install "flask[async]"
# or convert to sync:
def index(): ...

Defensive patterns

Strategy: fallback

Validate before calling

import importlib.util
if importlib.util.find_spec('asgiref') is None:
    raise SystemExit('Install: pip install flask[async]')

Type guard

import importlib.util
def async_support_available() -> bool:
    return importlib.util.find_spec('asgiref') is not None

Try / catch

try:
    from asgiref.sync import async_to_sync  # noqa
except ImportError:
    # define sync-only views
    ...
else:
    # async views are safe

Prevention

Pin flask[async] (or asgiref) in requirements.
Fail fast at startup with a find_spec check if you use async views.
Document the async dependency in the project README.

When it happens

Trigger: Defining an async def view, running under WSGI, and the asgiref package is absent. Flask calls async_to_sync internally which triggers the ImportError path.

Common situations: Installed Flask without the async extra (pip install flask instead of pip install flask[async]); a fresh/trimmed environment; asgiref removed by a dependency resolver.

Related errors

AI-assisted analysis of pallets/flask@3596b1ab61 (2026-08-11). Data as JSON: /api/errors/50d0e766d787f89d. Report an issue: GitHub.

Appendix: source

Thrown at src/flask/app.py:1099

    def async_to_sync(
        self, func: t.Callable[..., t.Coroutine[t.Any, t.Any, t.Any]]
    ) -> t.Callable[..., t.Any]:
        """Return a sync function that will run the coroutine function.

        .. code-block:: python

            result = app.async_to_sync(func)(*args, **kwargs)

        Override this method to change how the app converts async code
        to be synchronously callable.

        .. versionadded:: 2.0
        """
        try:
            from asgiref.sync import async_to_sync as asgiref_async_to_sync
        except ImportError:
            raise RuntimeError(
                "Install Flask with the 'async' extra in order to use async views."
            ) from None

        return asgiref_async_to_sync(func)

    def url_for(
        self,
        /,
        endpoint: str,
        *,
        _anchor: str | None = None,
        _method: str | None = None,
        _scheme: str | None = None,
        _external: bool | None = None,
        **values: t.Any,
    ) -> str:
        """Generate a URL to the given endpoint with the given values.

View on GitHub (pinned to 3596b1ab61)