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

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.

Source

Thrown at chromadb/utils/embedding_functions/jina_embedding_function.py:73

                Defaults to None.
            dimensions (int, optional): The number of dimensions to use for the Jina AI API.
                Defaults to None.
            embedding_type (str, optional): The type of embedding to use for the Jina AI API.
                Defaults to None.
            normalized (bool, optional): Whether to normalize the Jina AI API.
                Defaults to None.

        """
        try:
            import httpx
        except ImportError:
            raise ValueError(
                "The httpx python package is not installed. Please install it with `pip install httpx`"
            )
        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`"
            )

        if api_key is not None:
            warnings.warn(
                "Direct api_key configuration will not be persisted. "
                "Please use environment variables via api_key_env_var for persistent storage.",
                DeprecationWarning,
            )

        if os.getenv("JINA_API_KEY") is not None:
            self.api_key_env_var = "JINA_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(

View on GitHub (pinned to aecdd12c8a)

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

Example fix

# before
from chromadb.utils.embedding_functions import JinaEmbeddingFunction
ef = JinaEmbeddingFunction(model_name="jina-embeddings-v3")  # ValueError: PIL missing

# after
# pip install pillow
import importlib.util
if importlib.util.find_spec("PIL.Image") is None:
    raise SystemExit("pip install pillow")
ef = JinaEmbeddingFunction(model_name="jina-embeddings-v3")

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util

if importlib.util.find_spec("PIL.Image") is None:
    raise SystemExit("Jina EF needs pillow: pip install pillow")

from chromadb.utils.embedding_functions import JinaEmbeddingFunction
ef = JinaEmbeddingFunction(model_name="jina-embeddings-v3")

Try / catch

try:
    ef = JinaEmbeddingFunction(model_name="jina-embeddings-v3")
except ValueError as e:
    if "PIL" in str(e) or "pillow" in str(e):
        raise RuntimeError("pip install pillow") from e
    raise

Prevention

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

When it happens

Trigger: Constructing JinaEmbeddingFunction in an environment without pillow installed; headless server images that intentionally exclude pillow; environments where Pillow was replaced by a stub package.

Common situations: 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.

Related errors

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