run-llama/llama_index · error · ImportError

`llama-index-llms-openai` package cannot be found. Please in

Error message

`llama-index-llms-openai` package cannot be found. Please install it by using `pip install `llama-index-llms-openai`

What it means

MultiModalQueryEngine defaults its multi-modal LLM to OpenAIResponses(model='gpt-4.1') via a lazy import from llama_index.llms.openai. If that optional integration package is not installed, the ImportError is caught and re-raised with a message pointing at pip install llama-index-llms-openai. The message text has stray backticks (from a nested f-string), but the fix is simply installing the package or supplying your own LLM.

Source

Thrown at llama-index-core/llama_index/core/query_engine/multi_modal.py:91

        image_qa_template: Optional[BasePromptTemplate] = None,
        node_postprocessors: Optional[List[BaseNodePostprocessor]] = None,
        callback_manager: Optional[CallbackManager] = None,
        **kwargs: Any,
    ) -> None:
        self._retriever = retriever
        if multi_modal_llm:
            self._multi_modal_llm = multi_modal_llm
        else:
            try:
                from llama_index.llms.openai import (
                    OpenAIResponses,
                )  # pants: no-infer-dep

                self._multi_modal_llm = OpenAIResponses(
                    model="gpt-4.1", max_output_tokens=1000
                )
            except ImportError as e:
                raise ImportError(
                    "`llama-index-llms-openai` package cannot be found. "
                    "Please install it by using `pip install `llama-index-llms-openai`"
                )
        self._text_qa_template = text_qa_template or DEFAULT_TEXT_QA_PROMPT
        self._image_qa_template = image_qa_template or DEFAULT_TEXT_QA_PROMPT

        self._node_postprocessors = node_postprocessors or []
        callback_manager = callback_manager or CallbackManager([])
        for node_postprocessor in self._node_postprocessors:
            node_postprocessor.callback_manager = callback_manager

        super().__init__(callback_manager)

    def _get_prompts(self) -> Dict[str, Any]:
        """Get prompts."""
        return {"text_qa_template": self._text_qa_template}

    def _get_prompt_modules(self) -> PromptMixinType:

View on GitHub (pinned to afd0fef371)

Solutions

Install the integration: pip install llama-index-llms-openai.
Or pass your own LLM explicitly so the lazy OpenAI import never runs: MultiModalQueryEngine(..., multi_modal_llm=my_llm).
If you use a different provider, pass its multi-modal LLM (e.g. Anthropic, Gemini integration) instead of relying on the default.
For deployments, pin the integration package in requirements alongside llama-index-core to avoid environment drift.

Example fix

# before (no OpenAI integration installed)
engine = MultiModalQueryEngine(query_engine=text_engine)  # default LLM import fails

# after (option A: install)
# pip install llama-index-llms-openai
engine = MultiModalQueryEngine(query_engine=text_engine)

# after (option B: explicit LLM)
from llama_index.llms.anthropic import Anthropic
engine = MultiModalQueryEngine(
    query_engine=text_engine,
    multi_modal_llm=Anthropic(model="claude-sonnet-4-5"),
)

Defensive patterns

Strategy: fallback

Validate before calling

try:
    import llama_index.llms.openai  # noqa: F401
    HAS_OPENAI_INTEGRATION = True
except ImportError:
    HAS_OPENAI_INTEGRATION = False

if not HAS_OPENAI_INTEGRATION:
    # pass multi_modal_llm explicitly or install llama-index-llms-openai first
    assert multi_modal_llm is not None, "provide multi_modal_llm or pip install llama-index-llms-openai"

Try / catch

try:
    engine = MultiModalQueryEngine(query_engine=inner)
except ImportError:
    # either install the integration or supply your own multi-modal LLM
    from llama_index.llms.anthropic import Anthropic
    engine = MultiModalQueryEngine(
        query_engine=inner, multi_modal_llm=Anthropic(model="claude-sonnet-4-5")
    )

Prevention

Pin llama-index-llms-openai in requirements whenever you construct MultiModalQueryEngine without an explicit LLM.
Always pass multi_modal_llm when you intend a non-OpenAI provider.
Add a smoke test constructing the engine in CI to catch missing optional dependencies early.

When it happens

Trigger: Constructing MultiModalQueryEngine(...) without the multi_modal_llm argument on an environment where llama-index-llms-openai is absent — e.g. a minimal `pip install llama-index-core` install, slim Docker images, or a venv that only installed the integration packages you thought you needed.

Common situations: Installing llama-index-core alone (it does not depend on any LLM integration); CI images trimmed for size; using a non-OpenAI provider and assuming no OpenAI package is required — but the default constructor path imports it unconditionally when multi_modal_llm is omitted.

Related errors

AI-assisted analysis of run-llama/llama_index@afd0fef371 (2026-08-15). Data as JSON: /api/errors/b5072a64649fc7b7. Report an issue: GitHub.