run-llama/llama_index · error · ImportError

`llama-index-llms-openai` package not found, please run `pip

Error message

`llama-index-llms-openai` package not found, please run `pip install llama-index-llms-openai`

What it means

Thrown by resolve_llm (llama_index.core.llms.utils) when no explicit LLM was configured and llama-index falls back to its default OpenAI LLM, but the optional llama-index-llms-openai integration is not installed. Because core deliberately keeps provider packages optional, the ImportError tells you exactly which package to install.

Source

Thrown at llama-index-core/llama_index/core/llms/utils.py:59

        # if testing return mock llm
        if os.getenv("IS_TESTING"):
            from llama_index.core.llms.mock import MockLLM

            llm = MockLLM()
            llm.callback_manager = callback_manager or Settings.callback_manager
            return llm

        # return default OpenAI model. If it fails, return LlamaCPP
        try:
            from llama_index.llms.openai import OpenAI  # pants: no-infer-dep
            from llama_index.llms.openai.utils import (
                validate_openai_api_key,
            )  # pants: no-infer-dep

            llm = OpenAI()
            validate_openai_api_key(llm.api_key)  # type: ignore
        except ImportError:
            raise ImportError(
                "`llama-index-llms-openai` package not found, "
                "please run `pip install llama-index-llms-openai`"
            )
        except ValueError as e:
            raise ValueError(
                "\n******\n"
                "Could not load OpenAI model. "
                "If you intended to use OpenAI, please check your OPENAI_API_KEY.\n"
                "Original error:\n"
                f"{e!s}"
                "\n******"
            )

    if isinstance(llm, str):
        splits = llm.split(":", 1)
        is_local = splits[0]
        model_path = splits[1] if len(splits) > 1 else None
        if is_local != "local":

View on GitHub (pinned to afd0fef371)

Solutions

1. pip install llama-index-llms-openai (or install the llama-index meta-package which includes it).
2. Pass an explicit LLM you already have installed: Settings.llm = MyOtherLLM() or llm=... to the component.
3. For tests/offline, set an explicitly available LLM such as MockLLM to avoid the OpenAI default path.

Example fix

# before
index = VectorStoreIndex.from_documents(docs)  # no LLM set -> tries OpenAI default
# after
pip install llama-index-llms-openai
# or
from llama_index.core.llms.mock import MockLLM
Settings.llm = MockLLM()

def has_openai_integration() -> bool:
    try:
        import llama_index.llms.openai  # noqa: F401
        return True
    except ImportError:
        return False

if not has_openai_integration():
    from llama_index.core.llms.mock import MockLLM
    Settings.llm = MockLLM()  # or another installed LLM

def is_resolvable_llm(llm) -> bool:
    from llama_index.core.llms import LLM
    return isinstance(llm, LLM)

try:
    index = VectorStoreIndex.from_documents(docs)
except ImportError as e:
    if "llama-index-llms-openai" in str(e):
        raise SystemExit("Install it: pip install llama-index-llms-openai") from e
    raise

When it happens

Trigger: Constructing any component that auto-resolves an LLM (Settings.llm, VectorStoreIndex(...), from_documents, from_defaults without llm=) in an environment where llama-index-llms-openai is absent — e.g. installing only llama-index-core instead of the llama-index meta-package.

Common situations: Slim installs with just llama-index-core to save dependencies; Docker/CI images trimmed of extras; upgrading from old monolithic llama-index versions where OpenAI came bundled.

Related errors

• `llama-index-llms-langchain` package not found, please run `
• `llama-index-llms-llama-cpp` package not found, please run `
• `llama-index-llms-openai` package cannot be found. Please in
• WandbCallbackHandler is not installed. Please install it usi
• OpenInferenceCallbackHandler is not installed. Please instal

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