{"record":{"id":"43643a250367d659","repo":"apache/beam","slug":"pillow-is-required-to-use-huggingfaceimageembeddings-please","errorCode":null,"errorMessage":"Pillow is required to use HuggingfaceImageEmbeddings. Please install it with `pip install pillow`.","messagePattern":"Pillow is required to use HuggingfaceImageEmbeddings\\. Please install it with `pip install pillow`\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/ml/rag/embeddings/huggingface.py","lineNumber":174,"sourceCode":"            - ``load_model_args``: dict passed to\n              ``SentenceTransformer()`` constructor\n              (e.g. ``device``, ``cache_folder``,\n              ``trust_remote_code``).\n            - ``min_batch_size`` / ``max_batch_size``:\n              Control batching for inference.\n            - ``large_model``: If True, share the model\n              across processes to reduce memory usage.\n            - ``inference_args``: dict passed to\n              ``model.encode()``\n              (e.g. ``normalize_embeddings``).\n    \"\"\"\n    if not SentenceTransformer:\n      raise ImportError(\n          \"sentence-transformers is required to use \"\n          \"HuggingfaceImageEmbeddings. \"\n          \"Please install it with `pip install sentence-transformers`.\")\n    if not PILImage:\n      raise ImportError(\n          \"Pillow is required to use HuggingfaceImageEmbeddings. \"\n          \"Please install it with `pip install pillow`.\")\n    super().__init__(type_adapter=_create_hf_image_adapter(), **kwargs)\n    self.model_name = model_name\n    self.max_seq_length = max_seq_length\n    self.model_class = SentenceTransformer\n\n  def get_model_handler(self):\n    \"\"\"Returns model handler configured with RAG adapter.\"\"\"\n    return _SentenceTransformerModelHandler(\n        model_class=self.model_class,\n        max_seq_length=self.max_seq_length,\n        model_name=self.model_name,\n        load_model_args=self.load_model_args,\n        min_batch_size=self.min_batch_size,\n        max_batch_size=self.max_batch_size,\n        large_model=self.large_model)\n","sourceCodeStart":156,"sourceCodeEnd":192,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/ml/rag/embeddings/huggingface.py#L156-L192","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nembedder = HuggingfaceImageEmbeddings(model_name='clip-ViT-B-32')  # pillow missing\n\n// after\n# terminal: pip install pillow sentence-transformers\nembedder = HuggingfaceImageEmbeddings(model_name='clip-ViT-B-32')","handlingStrategy":"try-catch","validationCode":"import importlib.util\n\ndef pillow_available() -> bool:\n    return importlib.util.find_spec('PIL') is not None","typeGuard":null,"tryCatchPattern":"try:\n    embedder = HuggingfaceImageEmbeddings(model_name='clip-ViT-B-32')\nexcept ImportError as e:\n    if 'Pillow' in str(e):\n        logging.error('Install: pip install pillow')\n    raise","preventionTips":["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."],"tags":["python","apache-beam","importerror","pillow","optional-dependency"],"backgroundTag":"missing-optional-dependency","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}