ocrmypdf/OCRmyPDF · error · DpiError

Input file is an image, but has no resolution (DPI) in its…

Error message

Input file is an image, but has no resolution (DPI) in its metadata.  Estimate the resolution at which the image was scanned and specify it using --image-dpi.

What it means

Raised when an image input file has no DPI metadata at all. Without resolution info ocrmypdf cannot compute page dimensions for the output PDF, so it requires --image-dpi.

Solutions

Pass --image-dpi with the estimated scan resolution (commonly 300)
Embed DPI metadata in the image before running (Pillow: img.save(..., dpi=(300,300)))
Convert to PDF yourself with img2pdf specifying the layout

Example fix

# before
ocrmypdf photo.png out.pdf
# after
ocrmypdf --image-dpi 300 photo.png out.pdf

Defensive patterns

Strategy: validation

Validate before calling

from PIL import Image
with Image.open(src) as im:
    if 'dpi' not in im.info and not image_dpi:
        image_dpi = 300

Prevention

Normalize image inputs (embed DPI) before handing them to ocrmypdf

When it happens

Trigger: Passing an image with no 'dpi' key in its Pillow info dict and no --image-dpi option; raised in triage_image_file.

Common situations: PNG files (which often omit DPI), downloaded images, images processed by tools that strip metadata.

Related errors

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

Appendix: source

Thrown at src/ocrmypdf/_pipeline.py:117

            log.error("Input file is a file: %s", input_file)
        if input_file.stat().st_size == 0:
            log.error("Input file is empty: %s", input_file)
        raise UnsupportedImageFormatError() from e

    with im:
        log.info("Input file is an image")
        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"
                )

View on GitHub (pinned to 5074a0b0e1)