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

MultiModalLLMCompletionProgram.from_defaults defaults to OpenAIResponses (a multimodal model) when multi_modal_llm is None. That import lives in the optional llama-index-llms-openai package; if it is not installed, this ImportError is raised with install instructions. Supplying your own multi_modal_llm avoids the import entirely.

Source

Thrown at llama-index-core/llama_index/core/program/multi_modal_llm_program.py:66

        cls,
        output_parser: Optional[PydanticOutputParser] = None,
        output_cls: Optional[Type[BaseModel]] = None,
        prompt_template_str: Optional[str] = None,
        prompt: Optional[PromptTemplate] = None,
        multi_modal_llm: Optional[LLM] = None,
        image_documents: Optional[List[Union[ImageBlock, ImageNode]]] = None,
        verbose: bool = False,
        **kwargs: Any,
    ) -> "MultiModalLLMCompletionProgram":
        if multi_modal_llm is None:
            try:
                from llama_index.llms.openai import (
                    OpenAIResponses,
                )  # pants: no-infer-dep

                multi_modal_llm = OpenAIResponses(model="gpt-4.1", temperature=0)
            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`"
                )
        if prompt is None and prompt_template_str is None:
            raise ValueError("Must provide either prompt or prompt_template_str.")
        if prompt is not None and prompt_template_str is not None:
            raise ValueError("Must provide either prompt or prompt_template_str.")
        if prompt_template_str is not None:
            prompt = PromptTemplate(prompt_template_str)

        if output_parser is None:
            if output_cls is None:
                raise ValueError("Must provide either output_cls or output_parser.")
            output_parser = PydanticOutputParser(output_cls=output_cls)

        return cls(
            output_parser,
            prompt=cast(PromptTemplate, prompt),

View on GitHub (pinned to afd0fef371)

Solutions

pip install llama-index-llms-openai to enable the default OpenAIResponses model.
Or pass multi_modal_llm=<your multimodal LLM> explicitly so no OpenAI import is attempted.
Pin optional integrations in requirements to keep environments reproducible.

Example fix

# before
program = MultiModalLLMCompletionProgram.from_defaults(
    output_cls=Description,
    prompt_template_str="...",
)
# after
pip install llama-index-llms-openai
# or
program = MultiModalLLMCompletionProgram.from_defaults(
    output_keys_parser=None,
    output_cls=Description,
    image_documents=docs,
    multi_modal_llm=my_multimodal_llm,
    prompt_template_str="...",
)

Defensive patterns

Strategy: try-catch

Validate before calling

import importlib.util
if multi_modal_llm is None and importlib.util.find_spec("llama_index.llms.openai") is None:
    raise RuntimeError("pass multi_modal_llm or pip install llama-index-llms-openai")

Type guard

def has_openai_llm_package() -> bool:
    import importlib.util
    return importlib.util.find_spec("llama_index.llms.openai") is not None

Try / catch

try:
    program = MultiModalLLMCompletionProgram.from_defaults(...)
except ImportError as e:
    if "llama-index-llms-openai" in str(e):
        program = MultiModalLLMCompletionProgram.from_defaults(
            multi_modal_llm=my_fallback_multimodal_llm, ...
        )
    else:
        raise

Prevention

Always pass an explicit multi_modal_llm in library/wrapper code.
Declare llama-index-llms-openai in your dependency list if you rely on the default.

When it happens

Trigger: Calling MultiModalLLMCompletionProgram.from_defaults(...) without multi_modal_llm in an environment where llama-index-llms-openai is not installed (e.g. only llama-index-core is present).

Common situations: Minimal installs of llama-index-core; using a non-OpenAI multimodal provider but forgetting to pass it explicitly; CI environments trimmed of optional dependencies.

Related errors

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