{"record":{"id":"1d817d33072c1406","repo":"run-llama/llama_index","slug":"llama-index-llms-llama-cpp-package-not-found-pl","errorCode":null,"errorMessage":"`llama-index-llms-llama-cpp` package not found, please run `pip install llama-index-llms-llama-cpp`","messagePattern":"`llama-index-llms-llama-cpp` package not found, please run `pip install llama-index-llms-llama-cpp`","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/llms/utils.py","lineNumber":96,"sourceCode":"            raise ValueError(\n                \"llm must start with str 'local' or of type LLM or BaseLanguageModel\"\n            )\n        try:\n            from llama_index.llms.llama_cpp.llama_utils import (\n                completion_to_prompt,\n                messages_to_prompt,\n            )  # pants: no-infer-dep\n\n            from llama_index.llms.llama_cpp import LlamaCPP  # pants: no-infer-dep\n\n            llm = LlamaCPP(\n                model_path=model_path,\n                messages_to_prompt=messages_to_prompt,\n                completion_to_prompt=completion_to_prompt,\n                model_kwargs={\"n_gpu_layers\": 1},\n            )\n        except ImportError:\n            raise ImportError(\n                \"`llama-index-llms-llama-cpp` package not found, \"\n                \"please run `pip install llama-index-llms-llama-cpp`\"\n            )\n\n    elif BaseLanguageModel is not None and isinstance(llm, BaseLanguageModel):\n        # NOTE: if it's a langchain model, wrap it in a LangChainLLM\n        try:\n            from llama_index.llms.langchain import LangChainLLM  # pants: no-infer-dep\n\n            llm = LangChainLLM(llm=llm)\n        except ImportError:\n            raise ImportError(\n                \"`llama-index-llms-langchain` package not found, \"\n                \"please run `pip install llama-index-llms-langchain`\"\n            )\n    elif llm is None:\n        from llama_index.core.llms.mock import MockLLM\n","sourceCodeStart":78,"sourceCodeEnd":114,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/llms/utils.py#L78-L114","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\nSettings.llm = \"local:/models/qwen.gguf\"  # package missing -> ImportError\n# after\npip install llama-index-llms-llama-cpp\nSettings.llm = \"local:/models/qwen.gguf\"","handlingStrategy":"validation","validationCode":"def has_llama_cpp_integration() -> bool:\n    try:\n        import llama_index.llms.llama_cpp  # noqa: F401\n        return True\n    except ImportError:\n        return False\n\nfrom pathlib import Path\nassert has_llama_cpp_integration() and Path(model_path).exists(), \"install llama-index-llms-llama-cpp and check model path\"","typeGuard":"def is_local_llm_spec(value) -> bool:\n    return isinstance(value, str) and value.split(\":\", 1)[0] == \"local\"","tryCatchPattern":"try:\n    Settings.llm = resolve_llm(\"local:/models/m.gguf\")\nexcept ImportError as e:\n    if \"llama-cpp\" in str(e):\n        raise SystemExit(\"pip install llama-index-llms-llama-cpp\") from e\n    raise","preventionTips":["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."],"tags":["llama-index","install","llama-cpp","local-model","import-error"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}