run-llama/llama_index · critical · ImportError

`llama-index-embeddings-huggingface` package not found, plea

Error message

`llama-index-embeddings-huggingface` package not found, please run `pip install llama-index-embeddings-huggingface`

What it means

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.

Source

Thrown at llama-index-core/llama_index/core/embeddings/utils.py:113

                HuggingFaceEmbedding,
            )  # pants: no-infer-dep

            splits = embed_model.split(":", 1)
            is_local = splits[0]
            model_name = splits[1] if len(splits) > 1 else None
            if is_local != "local":
                raise ValueError(
                    "embed_model must start with str 'local' or of type BaseEmbedding"
                )

            cache_folder = os.path.join(get_cache_dir(), "models")
            os.makedirs(cache_folder, exist_ok=True)

            embed_model = HuggingFaceEmbedding(
                model_name=model_name, cache_folder=cache_folder
            )
        except ImportError:
            raise ImportError(
                "`llama-index-embeddings-huggingface` package not found, "
                "please run `pip install llama-index-embeddings-huggingface`"
            )

    if LCEmbeddings is not None and isinstance(embed_model, LCEmbeddings):
        try:
            from llama_index.embeddings.langchain import (
                LangchainEmbedding,
            )  # pants: no-infer-dep

            embed_model = LangchainEmbedding(embed_model)
        except ImportError as e:
            raise ImportError(
                "`llama-index-embeddings-langchain` package not found, "
                "please run `pip install llama-index-embeddings-langchain`"
            )

    if embed_model is None:

View on GitHub (pinned to afd0fef371)

Solutions

1. pip install llama-index-embeddings-huggingface (this pulls sentence-transformers/torch)
2. Or use the default OpenAI embedding instead: omit embed_model with a valid OPENAI_API_KEY
3. Or pass an already-constructed BaseEmbedding instance of whatever integration you do have installed

Example fix

// before
index = VectorStoreIndex.from_documents(docs, embed_model="local:BAAI/bge")
# ImportError: package not found

// after
# pip install llama-index-embeddings-huggingface
index = VectorStoreIndex.from_documents(docs, embed_model="local:BAAI/bge")

try:
    import llama_index.embeddings.huggingface  # noqa: F401
    can_local = True
except ImportError:
    can_local = False
if not can_local and isinstance(embed_model, str) and embed_model.startswith("local"):
    raise RuntimeError("pip install llama-index-embeddings-huggingface or use another embed model")

try:
    index = VectorStoreIndex.from_documents(docs, embed_model="local:BAAI/bge-small-en-v1.5")
except ImportError as e:
    if "llama-index-embeddings-huggingface" in str(e):
        index = VectorStoreIndex.from_documents(docs)  # fall back to default OpenAI
    else:
        raise

When it happens

Trigger: 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.

Common situations: Offline/air-gapped setups attempting the 'local' shortcut; slim Docker images; following quickstarts that assume the default pip install llama-index bundle.

Related errors

• `llama-index-embeddings-openai` package not found, please ru
• `llama-index-embeddings-clip` package not found, please run
• `llama-index-embeddings-langchain` package not found, please
• Invalid Embedding name: {name}
• embed_model must start with str 'local' or of type BaseEmbed

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