ocrmypdf.ocr(jpg_quality=...) is deprecated, use jpeg_qualit

Error message

ocrmypdf.ocr(jpg_quality=...) is deprecated, use jpeg_quality= instead.

What it means

Deprecation warning emitted by ocrmypdf.ocr(): the old jpg_quality keyword was renamed jpeg_quality. The value is transparently remapped, so behavior is unchanged — only the name changed.

Source

Thrown at src/ocrmypdf/api.py:463

            lang = expanded
        options_kwargs['languages'] = lang
    elif 'language' in options_kwargs:
        del options_kwargs['language']


def _remap_jpg_quality_to_jpeg_quality(options_kwargs: dict) -> None:
    """Map the deprecated 'jpg_quality' parameter to 'jpeg_quality'.

    'jpg_quality' was the original API parameter name. 'jpeg_quality' is the
    canonical OcrOptions field, matching the primary --jpeg-quality CLI flag.
    Prefer an explicitly-given 'jpeg_quality' if both are set.
    """
    if 'jpg_quality' not in options_kwargs:
        return
    old_value = options_kwargs.pop('jpg_quality')
    if old_value is None:
        return
    warn("ocrmypdf.ocr(jpg_quality=...) is deprecated, use jpeg_quality= instead.")
    if options_kwargs.get('jpeg_quality') is None:
        options_kwargs['jpeg_quality'] = old_value


def create_options(
    *, input_file: PathOrIO, output_file: PathOrIO, parser: ArgumentParser, **kwargs
) -> OcrOptions:
    """Construct an options object from the input/output files and keyword arguments.

    Args:
        input_file: Input file path or file object.
        output_file: Output file path or file object.
        parser: ArgumentParser object (kept for compatibility,
            may be used for plugin validation).
        **kwargs: Keyword arguments.

    Returns:
        OcrOptions: An options object containing the parsed arguments.

View on GitHub (pinned to 5074a0b0e1)

Solutions

Rename jpg_quality= to jpeg_quality= in your call
Silence during migration with warnings.filterwarnings('ignore', message='.*jpg_quality.*') if needed
Search your codebase for jpg_quality to catch all occurrences

Example fix

# before
ocrmypdf.ocr('in.pdf', 'out.pdf', jpg_quality=85)
# after
ocrmypdf.ocr('in.pdf', 'out.pdf', jpeg_quality=85)

Defensive patterns

Strategy: validation

Validate before calling

opts.pop('jpg_quality', None)  # migrate before calling ocr()

Prevention

Use current keyword names from the API docs
Grep codebase for deprecated kwargs after major-version upgrades

When it happens

Trigger: Calling ocrmypdf.ocr(..., jpg_quality=N) with a non-None value; create_options routes through _remap_jpg_quality_to_jpeg_quality which warns and remaps.

Common situations: Upgrading old scripts/tutorials written against pre-rename OCRmyPDF versions; copy-pasted Stack Overflow code.

Related errors

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