Registry / llm-agents / llama-index-embeddings-huggingface

llama-index-embeddings-huggingface

library0.7.0pypypi✓ verified 85d ago

This library integrates HuggingFace embedding models, including Sentence Transformer models, with LlamaIndex. It allows users to create embeddings for documents and queries for retrieval, supporting models like BGE, Mixedbread, Nomic, Jina, and E5. The current version is 0.7.0, and it's part of the LlamaIndex ecosystem, which maintains a regular release cadence for its integration packages.

llm-agents ai-ml

pip install llama-index-embeddings-huggingface

package ↗homepage ↗

INSTALL

IMPORT

SIG · LLAMA-INDEX-EMBEDD

llama-index-embeddings-huggingface

llm-agentspythonv0.7.0

Install

—

Import

—

Disk

—

Pass rate

0/ 10

Env Coverage0 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.7.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✕ build_error

4/8 runs

py 3.11

✕ build_error

4/8 runs

py 3.12

✕ build_error

4/8 runs

py 3.13

✕ build_error

7/8 runs

py 3.9

✕ build_error

✕ timeout

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

HuggingFaceEmbedding

✓ from llama_index.embeddings.huggingface import HuggingFaceEmbedding

✗ from llama_index.embeddings import HuggingFaceEmbedding

The class is located within the specific 'huggingface' submodule of `llama_index.embeddings`.

This example demonstrates how to initialize the `HuggingFaceEmbedding` class with a specified model (e.g., 'BAAI/bge-small-en-v1.5') and use it to either set the global embedding model for LlamaIndex or generate embeddings for a single piece of text directly.

from llama_index.core import Settings from llama_index.embeddings.huggingface import HuggingFaceEmbedding # Initialize the HuggingFaceEmbedding model # Loads BAAI/bge-small-en-v1.5 with the default torch backend embed_model = HuggingFaceEmbedding(model_name="BAAI/bge-small-en-v1.5") # Option 1: Set as the global embedding model for LlamaIndex Settings.embed_model = embed_model # Option 2: Generate embeddings for text directly text_to_embed = "Hello World! This is a test sentence." embeddings = embed_model.get_text_embedding(text_to_embed) print(f"Embeddings length: {len(embeddings)}") print(f"First 5 embedding values: {embeddings[:5]}")

Debug

Known issues

gotchaThe `sentence-transformers` package is a required peer dependency and must be installed separately. Failing to install it will lead to runtime errors when attempting to use `HuggingFaceEmbedding`.

fix

Ensure `pip install sentence-transformers` is run in your environment alongside `llama-index-embeddings-huggingface`.

affects: All versions

deprecatedSeveral parameters for `HuggingFaceEmbedding` such as `tokenizer_name`, `pooling`, `model`, and `tokenizer` are marked as deprecated in recent versions. Relying on them may lead to warnings or future breaking changes.

fix

Consult the latest LlamaIndex documentation for `HuggingFaceEmbedding` to use current parameter names and configurations.

affects: 0.7.0 and greater

breakingPython 3.9 is no longer supported. This library explicitly requires Python 3.10 or newer.

fix

Upgrade your Python environment to version 3.10 or higher.

affects: 0.7.0 and greater

gotchaFor advanced features like ONNX or OpenVINO model inference, additional 'extra' installations for `sentence-transformers` are required (e.g., `pip install sentence-transformers[onnx]` or `pip install sentence-transformers[openvino]`).

fix

Install the necessary `sentence-transformers` extras based on your chosen backend (e.g., `pip install 'sentence-transformers[onnx]'`) to enable optimized inference.

affects: All versions

gotchaThis library has a specific dependency range on `llama-index-core` (e.g., `>=0.13.0,<0.15` as of version 0.7.0). Using an incompatible `llama-index-core` version can lead to unexpected behavior or errors.

fix

Always check the `pyproject.toml` or `setup.py` of `llama-index-embeddings-huggingface` for the exact `llama-index-core` version compatibility and ensure your `llama-index-core` installation aligns with it.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'llama_index.embeddings.huggingface'

The `llama-index-embeddings-huggingface` package or one of its submodules has not been installed or is not accessible in the current Python environment.

fix

Install the package using pip: `pip install llama-index-embeddings-huggingface`

AttributeError: 'HuggingFaceEmbedding' object has no attribute '_model'

This error often occurs when the internal HuggingFace model (`_model`) within the `HuggingFaceEmbedding` instance fails to initialize properly, or when there's a version incompatibility between `llama-index-core` and `llama-index-embeddings-huggingface`, or if the object is modified (e.g., via `deepcopy`) in a way that loses the initialized model.

fix

Ensure `llama-index-core` and `llama-index-embeddings-huggingface` are compatible versions. Explicitly provide a `model_name` during initialization, e.g., `HuggingFaceEmbedding(model_name="BAAI/bge-small-en-v1.5")`, and verify the `sentence-transformers` library is also installed (`pip install sentence-transformers`). For deepcopy issues, re-initialize the embedding model after the copy.

ValueError: The `model_name` argument must be provided.

The `HuggingFaceEmbedding` class requires a `model_name` parameter to specify which Hugging Face model should be loaded to create embeddings.

fix

When initializing `HuggingFaceEmbedding`, pass a valid model identifier as the `model_name` argument, such as `embed_model = HuggingFaceEmbedding(model_name="BAAI/bge-small-en-v1.5")`.

ERROR: Cannot install llama-index-embeddings-huggingface==X.Y.Z because these package versions have conflicting dependencies.

This indicates a dependency conflict, most commonly with the `torch` (PyTorch) library, where the required version for `llama-index-embeddings-huggingface` clashes with an already installed version or another package's requirement.

fix

Try installing `torch` first with a version compatible with your `llama-index-embeddings-huggingface` version, then install the `llama-index` package. Alternatively, use a robust dependency resolver like `uv` (e.g., `pip install uv` then `uv pip install llama-index-embeddings-huggingface`) or consider using a fresh virtual environment with a Python version known to be compatible (e.g., Python 3.9 or 3.10 for older `llama-index` versions).

Upgrade

Version history

0.7.0latest on PyPI · released Mar 12, 2026

Audit

Dependencies

llama-index-corerequiredCore LlamaIndex framework for integration, specific version range required.

sentence-transformersrequiredUnderlying library for HuggingFace sentence transformer models.

huggingface-hubrequiredRequired for interacting with Hugging Face Hub, especially with the 'inference' extra.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://pypi.org/project/llama-index-embeddings-huggingface/ ↗

homepagehttps://www.llamaindex.ai ↗