ocrmypdf/OCRmyPDF · error · BadArgsError

--sidecar file must be different from the input and output f

Error message

--sidecar file must be different from the input and output files

What it means

Raised when the --sidecar file path equals the input or output file path, which would clobber one of those files when the text sidecar is written.

Source

Thrown at src/ocrmypdf/_validation.py:107

def check_options_sidecar(options: OcrOptions) -> None:
    if options.sidecar == '\0':
        if options.output_file == '-':
            raise BadArgsError("--sidecar filename needed when output file is stdout.")
        elif options.output_file == os.devnull:
            raise BadArgsError(
                "--sidecar filename needed when output file is /dev/null or NUL."
            )
        elif not isinstance(options.output_file, str | Path):
            # 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',

View on GitHub (pinned to 5074a0b0e1)

Solutions

Choose a distinct sidecar filename
Rely on the default derived name (output + '.txt') when possible

Example fix

# before
ocrmypdf --sidecar in.pdf in.pdf out.pdf
# after
ocrmypdf --sidecar out.txt in.pdf out.pdf

Defensive patterns

Strategy: validation

Validate before calling

import os
if sidecar and os.fspath(sidecar) in (os.fspath(input_file), os.fspath(output_file)):
    sidecar = str(output_file) + '.txt'

Prevention

Let ocrmypdf derive the sidecar name (output + '.txt') instead of hand-picking paths

When it happens

Trigger: options.sidecar resolving to the same path as options.input_file or options.output_file (string equality after fsync comparison); checked in check_options_sidecar.

Common situations: Auto-derived sidecar colliding with output name (e.g. output 'out.pdf.txt' vs explicit same path); explicitly passing --sidecar in.pdf by mistake.

Related errors

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