ocrmypdf/OCRmyPDF · error · BadArgsError

--clean is required for --unpaper-args

Error message

--clean is required for --unpaper-args

What it means

Raised when --unpaper-args is given without --clean. unpaper is only invoked as part of the clean preprocessing step, so its arguments are meaningless without it.

Source

Thrown at src/ocrmypdf/_validation.py:116

            # The '\0' sentinel is only ever set by the CLI, which always
            # supplies output_file as a plain path - not a stream. If this
            # somehow fires, the caller mixed a CLI-only sentinel with the
            # stream-based API.
            raise BadArgsError(
                "--sidecar filename needed when output file is not a path."
            )
        options.sidecar = os.fspath(options.output_file) + '.txt'
    if options.sidecar == options.input_file or options.sidecar == options.output_file:
        raise BadArgsError(
            "--sidecar file must be different from the input and output files"
        )


def check_options_preprocessing(options: OcrOptions) -> None:
    if options.clean_final:
        options.clean = True
    if options.unpaper_args and not options.clean:
        raise BadArgsError("--clean is required for --unpaper-args")
    if (
        options.rotate_pages_threshold != DEFAULT_ROTATE_PAGES_THRESHOLD
        and not options.rotate_pages
    ):
        raise BadArgsError("--rotate-pages is required for --rotate-pages-threshold")
    if options.clean:
        check_external_program(
            program='unpaper',
            package='unpaper',
            version_checker=unpaper.version,
            need_version='6.1',
            required_for="--clean, --clean-final",
        )


def check_options_strip(options: OcrOptions) -> None:
    """Reject options that cannot apply in strip mode.

View on GitHub (pinned to 5074a0b0e1)

Solutions

1. Add --clean (or --clean-final, which implies it) to the command
2. Remove --unpaper-args if cleaning is not wanted

Example fix

# before
ocrmypdf --unpaper-args '--layout double' in.pdf out.pdf
# after
ocrmypdf --clean --unpaper-args '--layout double' in.pdf out.pdf

if unpaper_args and not clean:
    clean = True  # or reject

When it happens

Trigger: options.unpaper_args set while options.clean is false (note: --clean-final implies clean); checked in check_options_preprocessing.

Common situations: Users adding unpaper options expecting unpaper to run independently; forgetting that --clean is the switch that invokes unpaper.

Related errors

• --redo-ocr (or --mode redo) is not currently compatible with
• --sidecar filename needed when output file is stdout.
• --sidecar filename needed when output file is /dev/null or N
• --rotate-pages is required for --rotate-pages-threshold
• --mode strip removes the OCR text layer without rasterizing

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