{"record":{"id":"5223b66f488b48eb","repo":"run-llama/llama_index","slug":"llama-index-embeddings-huggingface-package-not-f","errorCode":null,"errorMessage":"`llama-index-embeddings-huggingface` package not found, please run `pip install llama-index-embeddings-huggingface`","messagePattern":"`llama-index-embeddings-huggingface` package not found, please run `pip install llama-index-embeddings-huggingface`","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"critical","filePath":"llama-index-core/llama_index/core/embeddings/utils.py","lineNumber":113,"sourceCode":"                HuggingFaceEmbedding,\n            )  # pants: no-infer-dep\n\n            splits = embed_model.split(\":\", 1)\n            is_local = splits[0]\n            model_name = splits[1] if len(splits) > 1 else None\n            if is_local != \"local\":\n                raise ValueError(\n                    \"embed_model must start with str 'local' or of type BaseEmbedding\"\n                )\n\n            cache_folder = os.path.join(get_cache_dir(), \"models\")\n            os.makedirs(cache_folder, exist_ok=True)\n\n            embed_model = HuggingFaceEmbedding(\n                model_name=model_name, cache_folder=cache_folder\n            )\n        except ImportError:\n            raise ImportError(\n                \"`llama-index-embeddings-huggingface` package not found, \"\n                \"please run `pip install llama-index-embeddings-huggingface`\"\n            )\n\n    if LCEmbeddings is not None and isinstance(embed_model, LCEmbeddings):\n        try:\n            from llama_index.embeddings.langchain import (\n                LangchainEmbedding,\n            )  # pants: no-infer-dep\n\n            embed_model = LangchainEmbedding(embed_model)\n        except ImportError as e:\n            raise ImportError(\n                \"`llama-index-embeddings-langchain` package not found, \"\n                \"please run `pip install llama-index-embeddings-langchain`\"\n            )\n\n    if embed_model is None:","sourceCodeStart":95,"sourceCodeEnd":131,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/embeddings/utils.py#L95-L131","documentation":"When embed_model='local:<model>' (or 'local'), resolve_embed_model constructs a HuggingFaceEmbedding from the optional llama-index-embeddings-huggingface integration. If that package (or its transformers/torch deps) is not installed, the ImportError is re-raised with the pip command to fix it.","triggerScenarios":"Using embed_model='local:BAAI/bge-small-en-v1.5' on an environment without llama-index-embeddings-huggingface; fresh installs of llama-index-core only; broken torch/transformers installs that surface as ImportError inside the integration.","commonSituations":"Offline/air-gapped setups attempting the 'local' shortcut; slim Docker images; following quickstarts that assume the default pip install llama-index bundle.","solutions":["pip install llama-index-embeddings-huggingface (this pulls sentence-transformers/torch)","Or use the default OpenAI embedding instead: omit embed_model with a valid OPENAI_API_KEY","Or pass an already-constructed BaseEmbedding instance of whatever integration you do have installed"],"exampleFix":"// before\nindex = VectorStoreIndex.from_documents(docs, embed_model=\"local:BAAI/bge\")\n# ImportError: package not found\n\n// after\n# pip install llama-index-embeddings-huggingface\nindex = VectorStoreIndex.from_documents(docs, embed_model=\"local:BAAI/bge\")","handlingStrategy":"fallback","validationCode":"try:\n    import llama_index.embeddings.huggingface  # noqa: F401\n    can_local = True\nexcept ImportError:\n    can_local = False\nif not can_local and isinstance(embed_model, str) and embed_model.startswith(\"local\"):\n    raise RuntimeError(\"pip install llama-index-embeddings-huggingface or use another embed model\")","typeGuard":null,"tryCatchPattern":"try:\n    index = VectorStoreIndex.from_documents(docs, embed_model=\"local:BAAI/bge-small-en-v1.5\")\nexcept ImportError as e:\n    if \"llama-index-embeddings-huggingface\" in str(e):\n        index = VectorStoreIndex.from_documents(docs)  # fall back to default OpenAI\n    else:\n        raise","preventionTips":["Pin llama-index-embeddings-huggingface in requirements for any 'local:' usage","Pre-download models (HF_HOME cache) in Docker/CI to avoid runtime downloads","Feature-detect the integration import at startup and fail with a clear message"],"tags":["embeddings","huggingface","dependencies","installation"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}