{"record":{"id":"0c9525d19eabd8fa","repo":"chroma-core/chroma","slug":"the-pil-python-package-is-not-installed-please-in-0c9525","errorCode":null,"errorMessage":"The PIL python package is not installed. Please install it with `pip install pillow`","messagePattern":"The PIL python package is not installed\\. Please install it with `pip install pillow`","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/utils/embedding_functions/jina_embedding_function.py","lineNumber":73,"sourceCode":"                Defaults to None.\n            dimensions (int, optional): The number of dimensions to use for the Jina AI API.\n                Defaults to None.\n            embedding_type (str, optional): The type of embedding to use for the Jina AI API.\n                Defaults to None.\n            normalized (bool, optional): Whether to normalize the Jina AI API.\n                Defaults to None.\n\n        \"\"\"\n        try:\n            import httpx\n        except ImportError:\n            raise ValueError(\n                \"The httpx python package is not installed. Please install it with `pip install httpx`\"\n            )\n        try:\n            self._PILImage = importlib.import_module(\"PIL.Image\")\n        except ImportError:\n            raise ValueError(\n                \"The PIL python package is not installed. Please install it with `pip install pillow`\"\n            )\n\n        if api_key is not None:\n            warnings.warn(\n                \"Direct api_key configuration will not be persisted. \"\n                \"Please use environment variables via api_key_env_var for persistent storage.\",\n                DeprecationWarning,\n            )\n\n        if os.getenv(\"JINA_API_KEY\") is not None:\n            self.api_key_env_var = \"JINA_API_KEY\"\n        else:\n            self.api_key_env_var = api_key_env_var\n\n        self.api_key = api_key or os.getenv(self.api_key_env_var)\n        if not self.api_key:\n            raise ValueError(","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/utils/embedding_functions/jina_embedding_function.py#L55-L91","documentation":"Besides httpx, JinaEmbeddingFunction imports PIL.Image via importlib in __init__ to support multimodal (image) inputs, and converts a missing pillow install into this ValueError. Pillow is only needed because the EF must convert numpy-array images to PNG/base64 for the Jina API. The check happens at construction regardless of whether you ever send images.","triggerScenarios":"Constructing JinaEmbeddingFunction in an environment without pillow installed; headless server images that intentionally exclude pillow; environments where Pillow was replaced by a stub package.","commonSituations":"Server deployments built on slim base images; using Jina purely for text embeddings and assuming pillow is unnecessary (it is still required at init); requirements pruning tools removing 'unused' pillow.","solutions":["pip install pillow in the active environment","Verify: python -c \"import PIL.Image; print('ok')\"","If pillow cannot be installed, use a text-only HTTP EF without the pillow requirement"],"exampleFix":"# before\nfrom chromadb.utils.embedding_functions import JinaEmbeddingFunction\nef = JinaEmbeddingFunction(model_name=\"jina-embeddings-v3\")  # ValueError: PIL missing\n\n# after\n# pip install pillow\nimport importlib.util\nif importlib.util.find_spec(\"PIL.Image\") is None:\n    raise SystemExit(\"pip install pillow\")\nef = JinaEmbeddingFunction(model_name=\"jina-embeddings-v3\")","handlingStrategy":"validation","validationCode":"import importlib.util\n\nif importlib.util.find_spec(\"PIL.Image\") is None:\n    raise SystemExit(\"Jina EF needs pillow: pip install pillow\")\n\nfrom chromadb.utils.embedding_functions import JinaEmbeddingFunction\nef = JinaEmbeddingFunction(model_name=\"jina-embeddings-v3\")","typeGuard":null,"tryCatchPattern":"try:\n    ef = JinaEmbeddingFunction(model_name=\"jina-embeddings-v3\")\nexcept ValueError as e:\n    if \"PIL\" in str(e) or \"pillow\" in str(e):\n        raise RuntimeError(\"pip install pillow\") from e\n    raise","preventionTips":["Add pillow to the base image even for text-only Jina use — the constructor requires it","Prefer distro packages (libjpeg) + pip pillow together to avoid runtime PIL import errors","Check both httpx and PIL in one EF startup preflight"],"tags":["python","dependency","pip","pillow","jina","multimodal"],"backgroundTag":"missing-optional-dependency","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}