BerriAI/litellm · error · Exception

gemini image conversion failed please run `pip install Pillo

Error message

gemini image conversion failed please run `pip install Pillow`

What it means

In the Gemini vision conversion for non-URL images: the branch that handles base64/local images does 'from PIL import Image' and the import failed, so LiteLLM raises with the Pillow install hint. It fires for image strings containing 'base64' (or local references) rather than https:// URLs.

Source

Thrown at litellm/litellm_core_utils/prompt_templates/factory.py:3241

                    if isinstance(element, dict):
                        if element["type"] == "text":
                            prompt += element["text"]
                        elif element["type"] == "image_url":
                            image_url = element["image_url"]["url"]
                            images.append(image_url)
        # processing images passed to gemini
        processed_images: Final = []
        for img in images:
            if "https:/" in img:
                # Case 1: Image from URL
                image = _load_image_from_url(img)
                processed_images.append(image)

            else:
                try:
                    from PIL import Image
                except Exception:
                    raise Exception("gemini image conversion failed please run `pip install Pillow`")

                if "base64" in img:
                    # Case 2: Base64 image data
                    import base64
                    import io

                    # Extract the base64 image data
                    base64_data = img.split("base64,")[1]

                    # Decode the base64 image data
                    image_data = base64.b64decode(base64_data)

                    # Load the image from the decoded data
                    image = Image.open(io.BytesIO(image_data))
                else:
                    # Case 3: Image filepath (e.g. temp.jpeg) given
                    image = Image.open(img)
                processed_images.append(image)

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. pip install Pillow and pin it in your dependency manifest
2. Alternatively pass a clean data URI in a form that needs no re-encoding (or an https URL), avoiding the Pillow branch
3. Rebuild the deployment image with imaging extras (e.g. pip install 'litellm[extra_proxy]' or add Pillow explicitly)

Example fix

# before
$ pip install litellm  # no Pillow
litellm.completion(model="gemini/gemini-1.5-flash", messages=[..., {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}])

# after
$ pip install litellm Pillow
# same call now succeeds

def pillow_available() -> bool:
    try:
        import PIL  # noqa: F401
        return True
    except ImportError:
        return False

assert pillow_available(), "pip install Pillow before sending base64 images to Gemini"

When it happens

Trigger: Passing base64 data-URI images to the Gemini path that decodes and re-encodes them via Pillow when Pillow is not installed; slim containers or minimal installs lacking PIL.

Common situations: Same as 835: pruned Docker images, CI without imaging deps, serverless bundles that strip Pillow; appears only when the image is not a plain https URL.

Related errors

• image conversion failed please run `pip install Pillow`
• ollama image conversion failed please run `pip install Pillo
• Image url not in expected format. Example Expected input - "
• Please install litellm with `litellm[caching]` to use disk c
• Invalid image URL: {content_image_url}

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/84f71e402af376d8. Report an issue: GitHub.