Install & Compatibility
Where this runs
tested against v1.2.2 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 2.816s · 119.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 9.1s · import 2.528s · 110MB
116MB installed
● package 116MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ChatHuggingFace
✓ from langchain_huggingface.chat_models import ChatHuggingFace
✗ from langchain.llms import HuggingFaceHub
The original `langchain` package was monolithic; integrations are now separate.
HuggingFacePipeline
✓ from langchain_huggingface.llms import HuggingFacePipeline
✗ from langchain.llms import HuggingFacePipeline
Moved from the monolithic `langchain` package to the dedicated integration package.
HuggingFaceEmbeddings
✓ from langchain_huggingface.embeddings import HuggingFaceEmbeddings
✗ from langchain.embeddings import HuggingFaceEmbeddings
Embeddings were also moved to the dedicated integration package.
This quickstart demonstrates how to use `HuggingFacePipeline` to load a model and perform text generation. It uses `google/flan-t5-small` as an example, which works well for `text2text-generation` tasks. Ensure `transformers` and a deep learning backend (like `torch`) are installed.
import os
from langchain_huggingface.llms import HuggingFacePipeline
from langchain_core.prompts import PromptTemplate
from langchain_core.output_parsers import StrOutputParser
# Set your Hugging Face API token if accessing models from the Hub
# os.environ["HUGGINGFACEHUB_API_TOKEN"] = os.environ.get("HUGGINGFACEHUB_API_TOKEN", "")
# Initialize the HuggingFacePipeline with a small, accessible model
# Ensure 'transformers' and a deep learning backend (e.g., 'torch') are installed.
llm = HuggingFacePipeline.from_model_id(
model_id="google/flan-t5-small",
task="text2text-generation",
pipeline_kwargs={"max_new_tokens": 100},
# Pass token explicitly if needed, e.g., for private models or inference endpoints
# model_kwargs={"huggingfacehub_api_token": os.environ.get("HUGGINGFACEHUB_API_TOKEN", "")}
)
# Create a simple prompt template
template = "Question: {question}\nAnswer:"
prompt = PromptTemplate.from_template(template)
# Create a chain
chain = prompt | llm | StrOutputParser()
# Invoke the chain
question = "What is the capital of France?"
response = chain.invoke({"question": question})
print(response)
Debug
Known issues
breakingThe LangChain ecosystem transitioned from a monolithic 'langchain' package to modular 'langchain-*' integration packages. Components previously imported directly from `langchain` (e.g., `langchain.llms.HuggingFaceHub`) are now in `langchain-huggingface` (e.g., `langchain_huggingface.llms.HuggingFacePipeline`).fixUpdate all relevant import statements to target the new `langchain_huggingface` package structure (e.g., `from langchain_huggingface.llms import HuggingFacePipeline`).
affects: Migrations from langchain<0.1.0 to langchain-huggingface>=0.1.0
gotchaRunning large Hugging Face models locally requires significant hardware resources (RAM/VRAM). Attempting to load or run large models on insufficient hardware will lead to slow inference, out-of-memory errors, or crashes.fixFor local inference, choose smaller, quantized models, or ensure adequate GPU/CPU resources. For larger models, consider using Hugging Face Inference Endpoints or other cloud-based LLM APIs.
affects: All versions
gotchaMany Hugging Face models, especially when accessed via the Hugging Face Hub Inference API or for downloading private models, require an `HUGGINGFACEHUB_API_TOKEN`. Without it, you might encounter authentication errors or rate limits.fixObtain an API token from Hugging Face and set it as an environment variable (e.g., `export HUGGINGFACEHUB_API_TOKEN='hf_...'`) or pass it explicitly to the model constructor via `model_kwargs`.
affects: All versions
gotchaUsing `trust_remote_code=True` when loading models from Hugging Face can be a security risk as it executes arbitrary code from the model repository. This is sometimes required for custom architectures or tokenizers.fixOnly enable `trust_remote_code=True` for models from trusted sources. Understand the implications before using it. If possible, prefer models that do not require custom code.
affects: All versions
gotchaVersion conflicts can arise between `langchain-huggingface`, `langchain-core`, `transformers`, and `huggingface-hub`. These packages often have strict dependency ranges, and mismatched versions can cause unexpected behavior or import errors.fixAlways install `langchain-huggingface` first to allow `pip` to resolve compatible dependencies. Use a virtual environment to isolate dependencies. If conflicts occur, check the `install_requires` in `langchain-huggingface`'s `pyproject.toml` or `setup.py` for exact version ranges.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'langchain_huggingface'
The `langchain-huggingface` package is not installed in your Python environment or there's an issue with your environment setup.
fixEnsure the package is installed using `pip install langchain-huggingface`.
ImportError: Could not import sentence_transformers python package. Please install it with `pip install sentence-transformers`.
This error occurs when using `HuggingFaceEmbeddings` if the `sentence-transformers` library is not installed or an incompatible version is present (e.g., older than 5.2.0 for recent `langchain-huggingface` versions).
fixInstall or upgrade `sentence-transformers` to the required version: `pip install "sentence-transformers>=5.2.0"` or install with the full extra: `pip install langchain-huggingface[full]`.
ValueError: Model <model_id> is not supported for task text-generation and provider <provider>. Supported task: conversational.
You are attempting to use `HuggingFaceEndpoint` with a model that Hugging Face's inference providers route as a conversational/chat model, but `HuggingFaceEndpoint` defaults to the `text-generation` task.
fixIf the model is a chat model, use `ChatHuggingFace` instead with a list of messages. If you intend to use it for text generation, ensure the model/provider combination explicitly supports `text-generation` or consider adding `task="text-generation"` if appropriate for your model.
from langchain.llms import HuggingFacePipeline
This is an outdated import path. The `HuggingFacePipeline` class, along with `ChatHuggingFace` and `HuggingFaceEmbeddings`, has been moved to the dedicated `langchain_huggingface` package.
fixUpdate your import statement to `from langchain_huggingface import HuggingFacePipeline` (or `ChatHuggingFace`, `HuggingFaceEmbeddings`).
ImportError: cannot import name 'HuggingFacePipeline' from 'langchain_community.llms'
The `HuggingFacePipeline` class, along with other Hugging Face integrations, has moved to the dedicated `langchain_huggingface` package.
fixfrom langchain_huggingface.llms import HuggingFacePipeline
Upgrade
Version history
1.2.2latest on PyPI · released Apr 16, 2026
Audit
Dependencies
langchain-corerequiredCore LangChain functionalities; required by all LangChain integration packages.
huggingface-hubrequiredRequired for interacting with the Hugging Face Hub (downloading models, using inference APIs).
transformersrequiredRequired for loading and running Hugging Face models locally via pipelines.