Issue Station
Sign In
Tools hereToolbox

langchain - ✅(Solved) Fix Docs: langchain-huggingface README missing [full] extra — HuggingFaceEmbeddings silently fails without sentence-transformers>=5.2.0 [1 pull requests, 1 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
langchain-ai/langchain#35712•Fetched 2026-04-08 00:25:02
View on GitHub
Comments
1
Participants
2
Timeline
5
Reactions
0
Author
anix-lynchanix-lynch
Participants
agarwalkirtiagarwalkirtianix-lynchanix-lynch
Assignees
anix-lynchanix-lynch
Timeline (top)
assigned ×1closed ×1commented ×1cross-referenced ×1

The langchain-huggingface README only shows:

pip install langchain-huggingface

But sentence-transformers is an optional dependency (under [full] extra, requiring >=5.2.0). Users who follow the README and try to use HuggingFaceEmbeddings hit an ImportError at runtime with no guidance on how to fix it.

Error Message

ImportError: Could not import sentence_transformers python package. Please install it with pip install sentence-transformers.

Root Cause

Many projects have sentence-transformers>=2.2.0 pinned in requirements.txt from older tutorials. After migrating to langchain-huggingface, they get an ImportError even though sentence-transformers IS installed — because their version (2.x or 3.x) is below the 5.2.0 minimum.

Fix Action

Fixed

PR fix notes

PR #35713: docs(huggingface): add [full] install guidance and sentence-transformers>=5.2.0 migration note

Description (problem / solution / changelog)

Summary

Closes #35712

Adds a clear install note to libs/partners/huggingface/README.md explaining:

  1. The base pip install langchain-huggingface does not include sentence-transformers or transformers (they are optional deps under [full])
  2. Users who need HuggingFaceEmbeddings must install langchain-huggingface[full]
  3. Migration trap: users coming from langchain-community often have sentence-transformers>=2.2.0 pinned — but langchain-huggingface[full] requires >=5.2.0, causing silent ImportError

Changes

Single file: libs/partners/huggingface/README.md

Added a > Note: block immediately after the install command explaining:

  • pip install langchain-huggingface[full] for local inference use cases
  • The sentence-transformers version gap when migrating from langchain-community

Why

The current README only shows the base install. First-time users and migration users hit ImportError: Could not import sentence_transformers with no guidance. This is a pure doc fix — no code changes.

Checklist

  • Doc-only change
  • Covers both fresh installs and community → huggingface migrations
  • No breaking changes

Changed files

  • libs/partners/huggingface/README.md (modified, +16/-0)

Code Example

pip install langchain-huggingface

---

[project.optional-dependencies]
full = [
    "transformers>=5.0.0,<6.0.0",
    "sentence-transformers>=5.2.0,<6.0.0",
]

---

ImportError: Could not import sentence_transformers python package.
Please install it with `pip install sentence-transformers`.

---

# Old (langchain-community) — worked with sentence-transformers>=2.2.0
from langchain_community.embeddings import HuggingFaceEmbeddings

# New (langchain-huggingface) — requires sentence-transformers>=5.2.0
from langchain_huggingface import HuggingFaceEmbeddings

---

pip install langchain-huggingface sentence-transformers==2.7.0  # common older pin
python -c "from langchain_huggingface import HuggingFaceEmbeddings; HuggingFaceEmbeddings()"
# ImportError or unexpected behavior

---

# Base install
pip install langchain-huggingface

# For HuggingFaceEmbeddings (local inference with sentence-transformers)
pip install langchain-huggingface[full]
# or explicitly:
pip install langchain-huggingface "sentence-transformers>=5.2.0"
RAW_BUFFERClick to expand / collapse

Summary

The langchain-huggingface README only shows:

pip install langchain-huggingface

But sentence-transformers is an optional dependency (under [full] extra, requiring >=5.2.0). Users who follow the README and try to use HuggingFaceEmbeddings hit an ImportError at runtime with no guidance on how to fix it.

The Problem

From libs/partners/huggingface/pyproject.toml:

[project.optional-dependencies]
full = [
    "transformers>=5.0.0,<6.0.0",
    "sentence-transformers>=5.2.0,<6.0.0",
]

sentence-transformers is optional. The base install does not include it. But the README has no mention of [full] or the sentence-transformers requirement, so users hit:

ImportError: Could not import sentence_transformers python package.
Please install it with `pip install sentence-transformers`.

Migration Trap

This hits especially hard for users migrating from langchain-community:

# Old (langchain-community) — worked with sentence-transformers>=2.2.0
from langchain_community.embeddings import HuggingFaceEmbeddings

# New (langchain-huggingface) — requires sentence-transformers>=5.2.0
from langchain_huggingface import HuggingFaceEmbeddings

Many projects have sentence-transformers>=2.2.0 pinned in requirements.txt from older tutorials. After migrating to langchain-huggingface, they get an ImportError even though sentence-transformers IS installed — because their version (2.x or 3.x) is below the 5.2.0 minimum.

Minimal Reproduction

pip install langchain-huggingface sentence-transformers==2.7.0  # common older pin
python -c "from langchain_huggingface import HuggingFaceEmbeddings; HuggingFaceEmbeddings()"
# ImportError or unexpected behavior

Expected Fix

README should show:

# Base install
pip install langchain-huggingface

# For HuggingFaceEmbeddings (local inference with sentence-transformers)
pip install langchain-huggingface[full]
# or explicitly:
pip install langchain-huggingface "sentence-transformers>=5.2.0"

With a migration note that langchain-community accepted sentence-transformers>=2.2.0 but langchain-huggingface[full] requires >=5.2.0.

Environment

  • langchain-huggingface: 1.x
  • sentence-transformers: 2.2.0 (pinned from older project, common in ML pipelines)
  • Hit during migration from langchain_community.embeddings.HuggingFaceEmbeddings to langchain_huggingface
  • Discovered while migrating a resume embedding pipeline that used local HuggingFace models to avoid API costs

extent analysis

Fix Plan

Update README

  1. Add a note to the README explaining the optional dependency and the requirement for sentence-transformers:
# Optional Dependency
To use HuggingFaceEmbeddings, you need to install the full dependencies. You can do this by running:
```bash
pip install langchain-huggingface[full]

or explicitly:

pip install langchain-huggingface "sentence-transformers>=5.2.0"

Update Migration Note

  1. Add a migration note to the README explaining the change in requirements:
# Migration Note
If you are migrating from `langchain-community`, please note that `langchain-huggingface[full]` requires `sentence-transformers>=5.2.0`. If you have `sentence-transformers` pinned to a version below 5.2.0, you will need to update it to use HuggingFaceEmbeddings.

Update pyproject.toml

  1. Update the pyproject.toml file to reflect the correct optional dependencies:
[project.optional-dependencies]
full = [
    "transformers>=5.0.0,<6.0.0",
    "sentence-transformers>=5.2.0,<6.0.0",
]

Update requirements.txt

  1. Update the requirements.txt file to reflect the correct dependencies:
langchain-huggingface
sentence-transformers>=5.2.0

Update Example Code

  1. Update the example code to reflect the correct usage of HuggingFaceEmbeddings:
from langchain_huggingface import HuggingFaceEmbeddings
  1. Update the example code to handle the case where sentence-transformers is not installed:
try:
    from langchain_huggingface import HuggingFaceEmbeddings
except ImportError

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#ssr#installation#tensor shape#autograd error#agent setup#task chaining#parallel task#integration issue

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING