PrefectHQ/fastmcp · error · ImportError

The `openai` package is not installed. Please install `fastm

Error message

The `openai` package is not installed. Please install `fastmcp-slim[openai]` or add `openai` to your dependencies manually.

What it means

The OpenAI sampling handler imports the openai package at module load time. If openai is not installed, ImportError is raised with instructions to install the optional dependency via the fastmcp-slim[openai] extra.

Source

Thrown at fastmcp_slim/fastmcp/client/sampling/handlers/openai.py:46

    from openai.types.chat import (
        ChatCompletion,
        ChatCompletionAssistantMessageParam,
        ChatCompletionContentPartImageParam,
        ChatCompletionContentPartInputAudioParam,
        ChatCompletionContentPartParam,
        ChatCompletionContentPartTextParam,
        ChatCompletionMessageParam,
        ChatCompletionMessageToolCallParam,
        ChatCompletionSystemMessageParam,
        ChatCompletionToolChoiceOptionParam,
        ChatCompletionToolMessageParam,
        ChatCompletionToolParam,
        ChatCompletionUserMessageParam,
    )
    from openai.types.shared.chat_model import ChatModel
    from openai.types.shared_params import FunctionDefinition
except ImportError as e:
    raise ImportError(
        "The `openai` package is not installed. "
        "Please install `fastmcp-slim[openai]` or add `openai` to your dependencies manually."
    ) from e

# OpenAI only supports wav and mp3 for input audio
_OPENAI_AUDIO_FORMATS: dict[str, Literal["wav", "mp3"]] = {
    "audio/wav": "wav",
    "audio/x-wav": "wav",
    "audio/mp3": "mp3",
    "audio/mpeg": "mp3",
}

_OPENAI_IMAGE_MEDIA_TYPES: frozenset[str] = frozenset(
    {"image/jpeg", "image/png", "image/gif", "image/webp"}
)


def _image_content_to_openai_part(

View on GitHub (pinned to 1f02114297)

Solutions

Install the extra: pip install 'fastmcp-slim[openai]' (or uv add 'fastmcp-slim[openai]').
Or add openai to your project dependencies directly: pip install openai.
If using uv: uv sync --extra openai.
If you don't need OpenAI sampling, avoid importing/using the OpenAI handler and use another handler.

Example fix

// before
pip install fastmcp-slim
// after
pip install "fastmcp-slim[openai]"

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
if importlib.util.find_spec('openai') is None:
    raise SystemExit("Install the openai package: pip install 'fastmcp-slim[openai]'")

Type guard

null

Try / catch

try:
    from fastmcp.client.sampling.handlers.openai import OpenAIHandler
except ImportError:
    OpenAIHandler = None  # fall back to another handler

Prevention

Install fastmcp-slim with the [openai] extra in all environments.
Pin the extra in CI/docker images and requirements files.
Run a startup dependency check before using OpenAI sampling.

When it happens

Trigger: Importing fastmcp.client.sampling.handlers.openai (or triggering any code path that loads it, e.g. using OpenAI sampling handler) in an environment without the openai package installed.

Common situations: Fresh environments where fastmcp-slim was installed without extras; CI images missing optional deps; switching from full fastmcp to fastmcp-slim without updating dependency lists.

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