ocrmypdf.ocr(verbose=) is ignored. Use ocrmypdf.configure_lo

Error message

ocrmypdf.ocr(verbose=) is ignored. Use ocrmypdf.configure_logging().

What it means

ocrmypdf.ocr(verbose=...) has no effect; logging configuration must go through ocrmypdf.configure_logging(). A warning is emitted and the argument is ignored.

Source

Thrown at src/ocrmypdf/api.py:830

        # No new variable names should be assigned until these two steps are run
        create_options_kwargs = {
            k: v
            for k, v in locals().items()
            if k
            not in {
                'input_file_or_options',
                'input_file',
                'output_file',
                'kwargs',
                'plugin_manager',
            }
        }
        create_options_kwargs.update(kwargs)

        parser = get_parser()
        with _plugin_session(plugins, plugin_manager, parser=parser) as plugin_manager:
            if 'verbose' in kwargs:
                warn(
                    "ocrmypdf.ocr(verbose=) is ignored. "
                    "Use ocrmypdf.configure_logging()."
                )

            # Warn about deprecated jbig2 options and remove from kwargs
            if jbig2_lossy:
                warn(
                    "jbig2_lossy is deprecated and will be ignored. "
                    "Lossy JBIG2 has been removed due to character substitution risks."
                )
                create_options_kwargs.pop('jbig2_lossy', None)
            if jbig2_page_group_size:
                warn("jbig2_page_group_size is deprecated and will be ignored.")
                create_options_kwargs.pop('jbig2_page_group_size', None)

            options = create_options(
                input_file=input_file,
                output_file=output_file,

View on GitHub (pinned to 5074a0b0e1)

Solutions

Remove verbose= from the ocr() call
Call ocrmypdf.configure_logging() (e.g. with logging.DEBUG) to control verbosity
Update old scripts that predate the logging API change

Example fix

# before
ocrmypdf.ocr('in.pdf', 'out.pdf', verbose=True)
# after
ocrmypdf.configure_logging(ocrmypdf.logging.DEBUG)
ocrmypdf.ocr('in.pdf', 'out.pdf')

Defensive patterns

Strategy: validation

Validate before calling

kwargs.pop('verbose', None)\nocrmypdf.configure_logging(ocrmypdf.logging.INFO)

Prevention

Configure logging via configure_logging, never verbose=
Update pre-8.x era scripts when upgrading OCRmyPDF

When it happens

Trigger: Passing verbose= to ocrmypdf.ocr() (it's accepted solely for backward compatibility and dropped).

Common situations: Older OCRmyPDF 7.x-era scripts where verbose=True was valid; the public API moved verbosity control to configure_logging().

Related errors

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