apache/beam · error · ImportError

Pillow is required to use HuggingfaceImageEmbeddings. Please

Error message

Pillow is required to use HuggingfaceImageEmbeddings. Please install it with `pip install pillow`.

What it means

HuggingfaceImageEmbeddings.__init__ raises this ImportError when the Pillow (PIL) package is not installed, even if sentence-transformers is present. The constructor checks PILImage (imported as None when Pillow is missing) before proceeding, since decoding image bytes into PIL images is required for image embedding. Note the install hint says `pip install pillow` while the package import name is PIL.

Source

Thrown at sdks/python/apache_beam/ml/rag/embeddings/huggingface.py:174

            - ``load_model_args``: dict passed to
              ``SentenceTransformer()`` constructor
              (e.g. ``device``, ``cache_folder``,
              ``trust_remote_code``).
            - ``min_batch_size`` / ``max_batch_size``:
              Control batching for inference.
            - ``large_model``: If True, share the model
              across processes to reduce memory usage.
            - ``inference_args``: dict passed to
              ``model.encode()``
              (e.g. ``normalize_embeddings``).
    """
    if not SentenceTransformer:
      raise ImportError(
          "sentence-transformers is required to use "
          "HuggingfaceImageEmbeddings. "
          "Please install it with `pip install sentence-transformers`.")
    if not PILImage:
      raise ImportError(
          "Pillow is required to use HuggingfaceImageEmbeddings. "
          "Please install it with `pip install pillow`.")
    super().__init__(type_adapter=_create_hf_image_adapter(), **kwargs)
    self.model_name = model_name
    self.max_seq_length = max_seq_length
    self.model_class = SentenceTransformer

  def get_model_handler(self):
    """Returns model handler configured with RAG adapter."""
    return _SentenceTransformerModelHandler(
        model_class=self.model_class,
        max_seq_length=self.max_seq_length,
        model_name=self.model_name,
        load_model_args=self.load_model_args,
        min_batch_size=self.min_batch_size,
        max_batch_size=self.max_batch_size,
        large_model=self.large_model)

View on GitHub (pinned to 12126d8942)

Solutions

Install the dependency: pip install pillow (import name is PIL).
Add pillow to the requirements file shipped to your Beam runner.
If Pillow fails to install due to system libs, install the OS packages it needs (e.g. libjpeg/zlib) or use a standard Python base image.

Example fix

// before
embedder = HuggingfaceImageEmbeddings(model_name='clip-ViT-B-32')  # pillow missing

// after
# terminal: pip install pillow sentence-transformers
embedder = HuggingfaceImageEmbeddings(model_name='clip-ViT-B-32')

Defensive patterns

Strategy: try-catch

Validate before calling

import importlib.util

def pillow_available() -> bool:
    return importlib.util.find_spec('PIL') is not None

Try / catch

try:
    embedder = HuggingfaceImageEmbeddings(model_name='clip-ViT-B-32')
except ImportError as e:
    if 'Pillow' in str(e):
        logging.error('Install: pip install pillow')
    raise

Prevention

pip install pillow alongside sentence-transformers for image pipelines.
Remember the import name is PIL but the pip package is pillow.
Include pillow in Docker images and requirements files for workers.

When it happens

Trigger: Constructing HuggingfaceImageEmbeddings in an environment where Pillow was never installed or was removed (some slim images strip it); a dependency resolver uninstalling an incompatible Pillow version.

Common situations: Minimal Docker images for Beam workers without Pillow; conflicting Pillow builds (e.g. missing system libs) causing the guarded import to fail; forgetting that image embeddings require both sentence-transformers and Pillow.

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

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