chroma-core/chroma · error · ValueError

The PIL python package is not installed. Please install it w

Error message

The PIL python package is not installed. Please install it with `pip install pillow`

What it means

RoboflowEmbeddingFunction.__init__ imports PIL.Image via importlib.import_module and converts ImportError into this ValueError. Pillow is an optional dependency (needed to normalize/serialize images before POSTing them to the Roboflow inference API), so a bare chromadb install lacks it and construction fails — but only after the API-key check passes, which is why it can appear 'later' than expected.

Source

Thrown at chromadb/utils/embedding_functions/roboflow_embedding_function.py:64

                DeprecationWarning,
            )
        if os.getenv("ROBOFLOW_API_KEY") is not None:
            self.api_key_env_var = "ROBOFLOW_API_KEY"
        else:
            self.api_key_env_var = api_key_env_var

        self.api_key = api_key or os.getenv(self.api_key_env_var)
        if not self.api_key:
            raise ValueError(
                f"The {self.api_key_env_var} environment variable is not set."
            )

        self.api_url = api_url

        try:
            self._PILImage = importlib.import_module("PIL.Image")
        except ImportError:
            raise ValueError(
                "The PIL python package is not installed. Please install it with `pip install pillow`"
            )

        self._httpx = importlib.import_module("httpx")

    def __call__(self, input: Embeddable) -> Embeddings:
        """
        Generate embeddings for the given documents or images.

        Args:
            input: Documents or images to generate embeddings for.

        Returns:
            Embeddings for the documents or images.
        """
        embeddings = []

        for item in input:

View on GitHub (pinned to aecdd12c8a)

Solutions

pip install pillow into the running environment and add it to requirements.txt/pyproject.
On slim Docker images also install the native image libs if pillow wheels fail: apt-get install -y libjpeg-dev zlib1g-dev before pip install pillow.
Confirm you are installing into the same interpreter: python -m pip install pillow.
Quick sanity check before constructing: importlib.util.find_spec("PIL") should not be None.

Example fix

// before
ref = RoboflowEmbeddingFunction(api_key=...)  # ValueError: The PIL python package is not installed. Please install it with `pip install pillow`

# after
# shell: pip install pillow
import importlib.util
if importlib.util.find_spec("PIL") is None:
    raise RuntimeError("Run: pip install pillow")
ref = RoboflowEmbeddingFunction(api_key_env_var="ROBOFLOW_API_KEY")

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util

if importlib.util.find_spec("PIL") is None:
    raise RuntimeError("Pillow missing — run: pip install pillow")

ref = RoboflowEmbeddingFunction(api_key_env_var="ROBOFLOW_API_KEY")

Type guard

import importlib.util

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

Try / catch

try:
    ref = RoboflowEmbeddingFunction()
except ValueError as e:
    if "PIL" in str(e):
        raise RuntimeError("Install image deps: pip install pillow") from e
    raise

Prevention

Add pillow (and httpx) to your dependency manifest the moment you use image embeddings.
On slim Docker bases, install libjpeg/zlib system libs before pip installing pillow.
Add a find_spec("PIL") check to app startup when image ingestion is enabled.

When it happens

Trigger: Building RoboflowEmbeddingFunction in an environment without pillow installed: importlib.import_module("PIL.Image") raises ImportError, which the except clause re-raises as ValueError. Note the constructor imports httpx right after, so a missing httpx surfaces as a different (unwrapped) ImportError.

Common situations: Server/slim Docker images (python:3.x-slim) where pillow's libjpeg/zlib system libraries are absent; requirements lists chromadb but not pillow; upgrading Python versions where an old pillow wheel breaks and the package silently disappears; embedding images (not text) is the first code path that actually needs PIL.

Related errors

AI-assisted analysis of chroma-core/chroma@aecdd12c8a (2026-08-16). Data as JSON: /api/errors/76322fecf7f14454. Report an issue: GitHub.