PrefectHQ/fastmcp · error · ImportError

GenerativeUI requires prefab-ui. Install with: pip install '

Error message

GenerativeUI requires prefab-ui. Install with: pip install 'fastmcp[apps]'

What it means

GenerativeUI in fastmcp/apps/generative.py imports prefab_ui.generative and the prefab renderer helpers at module import time. If prefab-ui is absent, the ImportError is re-raised with an explicit install hint rather than a confusing bare module error. This keeps generative-UI support opt-in via the 'apps' extra.

Source

Thrown at fastmcp_slim/fastmcp/apps/generative.py:25

Requires ``fastmcp[apps]`` (prefab-ui).

Usage::

    from fastmcp import FastMCP
    from fastmcp.apps.generative import GenerativeUI

    mcp = FastMCP("My Server")
    mcp.add_provider(GenerativeUI())
"""

try:
    import prefab_ui.generative as _gen
    from prefab_ui.renderer import (
        get_generative_renderer_csp,
        get_generative_renderer_html,
    )
except ImportError as _exc:
    raise ImportError(
        "GenerativeUI requires prefab-ui. Install with: pip install 'fastmcp[apps]'"
    ) from _exc

import json
from collections.abc import AsyncIterator, Sequence
from contextlib import asynccontextmanager
from typing import Any

from fastmcp.apps.config import AppConfig, ResourceCSP, app_config_to_meta_dict
from fastmcp.server.providers.base import Provider
from fastmcp.server.providers.local_provider import LocalProvider
from fastmcp.tools.base import Tool
from fastmcp.utilities.logging import get_logger
from fastmcp.utilities.mime import UI_MIME_TYPE

logger = get_logger(__name__)

View on GitHub (pinned to 1f02114297)

Solutions

Install with pip install 'fastmcp[apps]'
If using fastmcp-slim, install the extra that includes prefab-ui
Re-run uv sync / pip install after changing dependency groups

Example fix

# before
from fastmcp.apps.generative import GenerativeUI  # ImportError

# after
# pip install 'fastmcp[apps]'
from fastmcp.apps.generative import GenerativeUI

Defensive patterns

Strategy: fallback

Validate before calling

import importlib.util
if importlib.util.find_spec('prefab_ui') is None:
    raise SystemExit("Install with: pip install 'fastmcp[apps]'")

Try / catch

try:
    from fastmcp.apps.generative import GenerativeUI
except ImportError as exc:
    if 'prefab-ui' in str(exc):
        print("Run: pip install 'fastmcp[apps]'")
    else:
        raise

Prevention

Pin the [apps] extra in pyproject/requirements
Test imports in a clean venv mirroring production
Keep prefab-ui updated alongside fastmcp

When it happens

Trigger: Importing fastmcp.apps.generative or constructing a GenerativeUI component in an environment without prefab_ui installed.

Common situations: Fresh venv or Docker image with plain fastmcp installed; upgrading fastmcp without reinstalling extras; following docs examples that use GenerativeUI without the apps extra.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

AI-assisted analysis of PrefectHQ/fastmcp@1f02114297 (2026-08-29). Data as JSON: /api/errors/b197f6c41bc063fd. Report an issue: GitHub.