PrefectHQ/fastmcp · error · ImportError

Choice requires prefab-ui. Install with: pip install 'fastmc

Error message

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

What it means

fastmcp.apps.choice depends on the optional prefab-ui package for its UI components. When prefab_ui is missing, the module's import-time try/except re-raises an ImportError with this message (chained to the underlying error), stopping the import.

Source

Thrown at fastmcp_slim/fastmcp/apps/choice.py:39

try:
    from prefab_ui.actions import SetState
    from prefab_ui.actions.mcp import SendMessage
    from prefab_ui.app import PrefabApp
    from prefab_ui.components import (
        H3,
        Button,
        Card,
        CardContent,
        CardFooter,
        CardHeader,
        Column,
        Muted,
        Text,
    )
    from prefab_ui.components.control_flow import If
    from prefab_ui.rx import STATE
except ImportError as _exc:
    raise ImportError(
        "Choice requires prefab-ui. Install with: pip install 'fastmcp[apps]'"
    ) from _exc

from fastmcp.apps.app import FastMCPApp


class Choice(FastMCPApp):
    """A Provider that lets the user choose from a set of options.

    The LLM calls ``choose`` with a prompt and a list of options.
    The user sees a card with one button per option. Clicking a button
    sends the selection back into the conversation via ``SendMessage``,
    triggering the LLM's next turn.

    Example::

        from fastmcp import FastMCP
        from fastmcp.apps.choice import Choice

View on GitHub (pinned to 1f02114297)

Solutions

Run `pip install 'fastmcp[apps]'` to add prefab-ui.
Confirm `import prefab_ui` succeeds in the target environment.
Avoid importing fastmcp.apps.choice when the UI extra is not part of your deployment.

Example fix

// before
uv pip install fastmcp
// after
uv pip install 'fastmcp[apps]'

Defensive patterns

Strategy: fallback

Validate before calling

import importlib.util
if importlib.util.find_spec("prefab_ui") is None:
    raise SystemExit("Install fastmcp[apps] to use fastmcp.apps.choice")

Try / catch

try:
    from fastmcp.apps.choice import Choice
except ImportError as e:
    Choice = None
    print(f"Choice UI unavailable: {e}; install 'fastmcp[apps]'")

Prevention

Include the [apps] extra in all environments that use choice UIs
Add an import smoke test for fastmcp.apps.choice in CI
Keep extras synchronized between dev and prod dependency files

When it happens

Trigger: `from fastmcp.apps.choice import Choice` (or importing the module) in an environment without prefab-ui installed.

Common situations: fastmcp installed without the [apps] extra; CI or server images built without optional deps; upgrading environments where extras were dropped.

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/b2171f00b0d3d644. Report an issue: GitHub.