apache/beam · error · ImportError

sentence-transformers is required to use…

Error message

sentence-transformers is required to use SentenceTransformerEmbeddings.Please install it with using `pip install sentence-transformers`.

What it means

SentenceTransformerEmbeddings depends on the optional sentence-transformers package. The module captures the import result into SentenceTransformer; if the package is not installed, __init__ raises ImportError instructing the user to install it with pip install sentence-transformers.

Solutions

1. Install the dependency: pip install sentence-transformers.
2. Add sentence-transformers to your requirements.txt / setup.py extra so workers get it too.
3. Use the apache-beam[ml] extra if it covers the dependency, and pin compatible versions of transformers/torch alongside it.

Example fix

// before
embeddings = SentenceTransformerEmbeddings(model_name='all-MiniLM-L6-v2')
// after
# terminal: pip install sentence-transformers
embeddings = SentenceTransformerEmbeddings(model_name='all-MiniLM-L6-v2')

try:
    import sentence_transformers
except ImportError:
    raise SystemExit('Install with: pip install sentence-transformers')

def sentence_transformers_available() -> bool:
    try:
        import sentence_transformers
        return True
    except ImportError:
        return False

try:
    embeddings = SentenceTransformerEmbeddings(model_name='all-MiniLM-L6-v2')
except ImportError:
    pip_install(['sentence-transformers'])
    embeddings = SentenceTransformerEmbeddings(model_name='all-MiniLM-L6-v2')

When it happens

Trigger: Instantiating SentenceTransformerEmbeddings(...) in an environment where sentence-transformers is not installed, so SentenceTransformer is None; deploying a pipeline to runners/workers without the extra dependency.

Common situations: Fresh virtualenv or CI job missing the optional dependency; Dataflow/Flink workers launched without the dependency in requirements; a requirements file that includes apache-beam but not sentence-transformers.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• AWS dependencies are not installed, and no alternative…
• Azure dependencies are not installed. Unable to run.
• Bigquery dependencies are not installed.
• Bigquery dependencies are not installed.
• Can't find a Python executable.

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/931e14d9b0b39004. Report an issue: GitHub.

Appendix: source

Thrown at sdks/python/apache_beam/ml/transforms/embeddings/huggingface.py:72

      model_name: str,
      model_class: Callable,
      load_model_args: Optional[dict] = None,
      min_batch_size: Optional[int] = None,
      max_batch_size: Optional[int] = None,
      max_seq_length: Optional[int] = None,
      large_model: bool = False,
      **kwargs):
    self._max_seq_length = max_seq_length
    self.model_name = model_name
    self._model_class = model_class
    self._load_model_args = load_model_args
    self._min_batch_size = min_batch_size
    self._max_batch_size = max_batch_size
    self._large_model = large_model
    self._kwargs = kwargs

    if not SentenceTransformer:
      raise ImportError(
          "sentence-transformers is required to use "
          "SentenceTransformerEmbeddings."
          "Please install it with using `pip install sentence-transformers`.")

  def run_inference(
      self,
      batch: Sequence[str],
      model: SentenceTransformer,
      inference_args: Optional[dict[str, Any]] = None,
  ):
    inference_args = inference_args or {}
    return model.encode(batch, **inference_args)

  def load_model(self):
    model = self._model_class(self.model_name, **self._load_model_args)
    if self._max_seq_length:
      model.max_seq_length = self._max_seq_length
    return model

View on GitHub (pinned to 12126d8942)