ocrmypdf/OCRmyPDF · error · UnsupportedImageFormatError

The input image has an alpha channel. Remove the alpha chann

Error message

The input image has an alpha channel. Remove the alpha channel first.

What it means

Raised when the input image mode is RGBA or LA, i.e. it has an alpha (transparency) channel. img2pdf cannot embed alpha channels into a PDF image, so the alpha must be removed before conversion.

Source

Thrown at src/ocrmypdf/_pipeline.py:124

        if 'dpi' in im.info:
            if im.info['dpi'] <= (96, 96) and not options.image_dpi:
                log.info("Image size: (%d, %d)", *im.size)
                log.info("Image resolution: (%d, %d)", *im.info['dpi'])
                raise DpiError(
                    "Input file is an image, but the resolution (DPI) is "
                    "not credible.  Estimate the resolution at which the "
                    "image was scanned and specify it using --image-dpi."
                )
        elif not options.image_dpi:
            log.info("Image size: (%d, %d)", *im.size)
            raise DpiError(
                "Input file is an image, but has no resolution (DPI) "
                "in its metadata.  Estimate the resolution at which "
                "image was scanned and specify it using --image-dpi."
            )

        if im.mode in ('RGBA', 'LA'):
            raise UnsupportedImageFormatError(
                "The input image has an alpha channel. Remove the alpha channel first."
            )

        if 'iccprofile' not in im.info:
            if im.mode == 'RGB':
                log.info("Input image has no ICC profile, assuming sRGB")
            elif im.mode == 'CMYK':
                raise UnsupportedImageFormatError(
                    "Input CMYK image has no ICC profile, not usable"
                )

    try:
        log.info("Image seems valid. Try converting to PDF...")
        layout_fun = img2pdf.default_layout_fun
        if options.image_dpi:
            layout_fun = img2pdf.get_fixed_dpi_layout_fun(
                Resolution(options.image_dpi, options.image_dpi)
            )

View on GitHub (pinned to 5074a0b0e1)

Solutions

Flatten the image onto a white background and save without alpha
Convert to RGB mode before running ocrmypdf

Example fix

# before
ocrmypdf logo.png out.pdf
# after (Python)
from PIL import Image
im = Image.open('logo.png').convert('RGB')
im.save('logo_rgb.png')
# then: ocrmypdf logo_rgb.png out.pdf

Defensive patterns

Strategy: validation

Validate before calling

from PIL import Image
with Image.open(src) as im:
    if im.mode in ('RGBA', 'LA'):
        bg = Image.new('RGB', im.size, (255, 255, 255))
        bg.paste(im, mask=im.split()[-1])
        bg.save(src)

Prevention

Flatten alpha in your preprocessing pipeline for all PNG inputs

When it happens

Trigger: Input image with mode 'RGBA' or 'LA' (PNG with transparency most commonly); checked in triage_image_file before img2pdf conversion.

Common situations: PNG exports from design tools or screenshots with transparency; logos or web images.

Related errors

AI-assisted analysis of ocrmypdf/OCRmyPDF@5074a0b0e1 (2026-08-27). Data as JSON: /api/errors/e7a15a0c7cf75ec4. Report an issue: GitHub.