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

The third import in OpenCLIPEmbeddingFunction.__init__ is PIL.Image (importlib.import_module("PIL.Image")), converted to ValueError with the pip hint on ImportError. Pillow is required because the EF's __call__ opens each image URI with PIL to run open_clip's preprocessing pipeline (resize/crop/normalize) before inference. The import name is PIL.Image but the pip package is pillow — a classic mismatch.

Source

Thrown at chromadb/utils/embedding_functions/open_clip_embedding_function.py:58

        """
        try:
            import open_clip
        except ImportError:
            raise ValueError(
                "The open_clip python package is not installed. Please install it with `pip install open-clip-torch`. https://github.com/mlfoundations/open_clip"
            )

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

        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.model_name = model_name
        self.checkpoint = checkpoint
        self.device = device

        model, _, preprocess = open_clip.create_model_and_transforms(
            model_name=model_name, pretrained=checkpoint
        )
        self._model = model
        self._model.to(device)
        self._preprocess = preprocess
        self._tokenizer = open_clip.get_tokenizer(model_name=model_name)

    def _encode_image(self, image: Image) -> Embedding:
        """
        Encode an image using the Open CLIP model.

View on GitHub (pinned to aecdd12c8a)

Solutions

pip install pillow (the import name PIL comes from the pillow package)
If a version conflict uninstalled it, resolve the pin: pip install 'pillow>=10' alongside your other imaging deps
Verify: python -c "from PIL import Image; print(Image.__version__)"

Example fix

// before
fn = OpenCLIPEmbeddingFunction()  # ValueError: PIL not installed

// after (shell)
pip install pillow
// then
fn = OpenCLIPEmbeddingFunction()

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
if importlib.util.find_spec("PIL") is None:
    raise SystemExit("pillow missing: pip install pillow")

Try / catch

try:
    fn = OpenCLIPEmbeddingFunction()
except ValueError as e:
    if "PIL" in str(e):
        raise SystemExit("Run: pip install pillow") from e
    raise

Prevention

Remember pip name pillow vs import name PIL
Watch for pillow being uninstalled by resolver conflicts; pin it in the lockfile
Include pillow in image builds that run any image-processing EF

When it happens

Trigger: Constructing OpenCLIPEmbeddingFunction() without pillow installed; installing the old/abandoned `pil` or `Pillow` capitalization confusion; pillow uninstalled by a resolver conflict (some libraries pin pillow versions aggressively); headless systems where pillow was trimmed from the base image.

Common situations: Minimal Docker images; dependency conflicts with other imaging libraries (e.g. torchvision, matplotlib pulling different pillow pins); using `pip install PIL` (wrong package, use pillow).

Related errors

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