run-llama/llama_index · error · ImportError

`llama-index-llms-llama-cpp` package not found, please run `

Error message

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

What it means

resolve_llm only auto-loads a local model when you pass a string starting with 'local'; that branch imports LlamaCPP from the optional llama-index-llms-llama-cpp integration. If the package is not installed, the ImportError surfaces with the exact pip command, because core cannot ship the llama.cpp bindings itself.

Source

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

            raise ValueError(
                "llm must start with str 'local' or of type LLM or BaseLanguageModel"
            )
        try:
            from llama_index.llms.llama_cpp.llama_utils import (
                completion_to_prompt,
                messages_to_prompt,
            )  # pants: no-infer-dep

            from llama_index.llms.llama_cpp import LlamaCPP  # pants: no-infer-dep

            llm = LlamaCPP(
                model_path=model_path,
                messages_to_prompt=messages_to_prompt,
                completion_to_prompt=completion_to_prompt,
                model_kwargs={"n_gpu_layers": 1},
            )
        except ImportError:
            raise ImportError(
                "`llama-index-llms-llama-cpp` package not found, "
                "please run `pip install llama-index-llms-llama-cpp`"
            )

    elif BaseLanguageModel is not None and isinstance(llm, BaseLanguageModel):
        # NOTE: if it's a langchain model, wrap it in a LangChainLLM
        try:
            from llama_index.llms.langchain import LangChainLLM  # pants: no-infer-dep

            llm = LangChainLLM(llm=llm)
        except ImportError:
            raise ImportError(
                "`llama-index-llms-langchain` package not found, "
                "please run `pip install llama-index-llms-langchain`"
            )
    elif llm is None:
        from llama_index.core.llms.mock import MockLLM

View on GitHub (pinned to afd0fef371)

Solutions

pip install llama-index-llms-llama-cpp.
If you didn't intend local mode, replace the string with a proper LLM instance (the 'local...' prefix is what routed you here).
Verify the model path exists after install to avoid the next failure.

Example fix

# before
Settings.llm = "local:/models/qwen.gguf"  # package missing -> ImportError
# after
pip install llama-index-llms-llama-cpp
Settings.llm = "local:/models/qwen.gguf"

Defensive patterns

Strategy: validation

Validate before calling

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

from pathlib import Path
assert has_llama_cpp_integration() and Path(model_path).exists(), "install llama-index-llms-llama-cpp and check model path"

Type guard

def is_local_llm_spec(value) -> bool:
    return isinstance(value, str) and value.split(":", 1)[0] == "local"

Try / catch

try:
    Settings.llm = resolve_llm("local:/models/m.gguf")
except ImportError as e:
    if "llama-cpp" in str(e):
        raise SystemExit("pip install llama-index-llms-llama-cpp") from e
    raise

Prevention

Add llama-index-llms-llama-cpp to requirements wherever 'local' LLM strings are used.
Verify the GGUF model path exists before resolution.
Keep local-mode config behind an environment check in shared codebases.

When it happens

Trigger: Calling any LLM-resolving API with llm='local' or 'local:/path/to/model.gguf' while llama-index-llms-llama-cpp is not installed in the environment.

Common situations: Testing local-mode configs on a machine that only installed OpenAI integrations; CI environments built from a requirements list that omits the llama-cpp extra; assuming 'local' support is built into core.

Related errors

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