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

After importing cohere, the constructor separately imports PIL.Image (via importlib) because image inputs are encoded as PNG then base64 data URIs before being sent to Cohere. A missing Pillow install produces this dedicated ValueError, independent of whether cohere itself is present.

Source

Thrown at chromadb/utils/embedding_functions/cohere_embedding_function.py:36

class CohereEmbeddingFunction(EmbeddingFunction[Embeddable]):
    def __init__(
        self,
        api_key: Optional[str] = None,
        model_name: str = "large",
        api_key_env_var: str = "CHROMA_COHERE_API_KEY",
    ):
        try:
            import cohere
        except ImportError:
            raise ValueError(
                "The cohere python package is not installed. Please install it with `pip install cohere`"
            )

        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("COHERE_API_KEY") is not None:
            self.api_key_env_var = "COHERE_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."

View on GitHub (pinned to aecdd12c8a)

Solutions

pip install pillow, then re-instantiate the embedding function.
Keep pillow pinned next to chromadb and cohere in your dependency manifest.
Check with python -c 'import PIL.Image' in the runtime interpreter.

Example fix

# before
import cohere  # ok
import PIL.Image  # ModuleNotFoundError -> ValueError: PIL not installed

# after
# pip install pillow
from chromadb.utils.embedding_functions import CohereEmbeddingFunction
ef = CohereEmbeddingFunction()  # constructs cleanly

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
if importlib.util.find_spec('PIL') is None:
    raise SystemExit('pip install pillow before using CohereEmbeddingFunction')

Try / catch

try:
    ef = CohereEmbeddingFunction()
except ValueError as e:
    if 'PIL' in str(e) or 'pillow' in str(e):
        raise SystemExit(f'Dependency missing: {e}') from e
    raise

Prevention

The Cohere EF always imports PIL at construction - install pillow even for text-only use.
Keep pillow pinned next to cohere and chromadb.
Add optional-dependency checks to your app's boot sequence.

When it happens

Trigger: Constructing CohereEmbeddingFunction in an environment that has cohere but not Pillow - common when installing cohere alone, since pillow is not a hard Chroma dependency.

Common situations: Text-only users hit it because the constructor always imports PIL even if you never send images; slim images that strip pillow; pillow listed only as an optional/dev dependency.

Related errors

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