ocrmypdf/OCRmyPDF · error · NotImplementedError

--remove-background is temporarily not implemented

Error message

--remove-background is temporarily not implemented

What it means

Raised because background removal is temporarily unimplemented: when any image on the page has bpc > 1 (grayscale/color), --remove-background raises NotImplementedError. The leptonica call is commented out in the source.

Source

Thrown at src/ocrmypdf/_pipeline.py:627

        input_file=input_file,
        output_file=output_file,
        raster_device=device,
        raster_dpi=canvas_dpi,
        page_dpi=page_dpi,
        pageno=pageinfo.pageno + 1,
        rotation=correction,
        filter_vector=remove_vectors,
        stop_on_soft_error=not page_context.options.continue_on_soft_render_error,
        options=page_context.options,
        use_cropbox=False,
    )
    return output_file


def preprocess_remove_background(input_file: Path, page_context: PageContext) -> Path:
    """Remove the background from the input image (temporarily disabled)."""
    if any(image.bpc > 1 for image in page_context.pageinfo.images):
        raise NotImplementedError("--remove-background is temporarily not implemented")
        # output_file = page_context.get_path('pp_rm_bg.png')
        # leptonica.remove_background(input_file, output_file)
        # return output_file
    log.info("background removal skipped on mono page")
    return input_file


def preprocess_deskew(input_file: Path, page_context: PageContext) -> Path:
    """Deskews the input image using the OCR engine and saves the output to a file.

    Args:
        input_file: The input image file to deskew.
        page_context: The context of the page being processed.

    Returns:
        Path: The path to the deskewed image file.
    """
    output_file = page_context.get_path('pp_deskew.png')

View on GitHub (pinned to 5074a0b0e1)

Solutions

1. Remove --remove-background from your command
2. Do background cleanup externally beforehand (e.g. ImageMagick/leptonica -level, scan preprocessing tools)

Example fix

# before
ocrmypdf --remove-background in.pdf out.pdf
# after
ocrmypdf in.pdf out.pdf

if getattr(opts, 'remove_background', False):
    raise SystemExit('--remove-background is not implemented; remove the flag')

When it happens

Trigger: Passing --remove-background on a page containing grayscale or color images (bpc > 1); mono pages skip removal with a log message instead.

Common situations: Users with old scripts or docs referencing --remove-background; upgrading ocrmypdf versions where the feature was disabled.

Related errors

• --redo-ocr (or --mode redo) is not currently compatible with
• Since you specified `--output-type none`, the output file {s
• Input file is an image, but the resolution (DPI) is not cred
• Input file is an image, but has no resolution (DPI) in its m
• The input image has an alpha channel. Remove the alpha chann

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