ocrmypdf/OCRmyPDF · error · BadArgsError

--sidecar filename needed when output file is stdout.

Error message

--sidecar filename needed when output file is stdout.

What it means

Raised when --sidecar was requested without a filename while the output file is stdout ('-'). Since the text sidecar cannot be inferred from a stream, an explicit filename is required.

Source

Thrown at src/ocrmypdf/_validation.py:92

            "requested languages: \n"
            f"{lang_text}\n"
            "Please install the appropriate language data for your OCR engine.\n"
            "\n"
            "See the online documentation for instructions:\n"
            "    https://ocrmypdf.readthedocs.io/en/latest/languages.html\n"
            "\n"
            "Note: most languages are identified by a 3-letter ISO 639-2 Code.\n"
            "For example, English is 'eng', German is 'deu', and Spanish is 'spa'.\n"
            "Simplified Chinese is 'chi_sim' and Traditional Chinese is 'chi_tra'."
            "\n"
        )
        raise MissingDependencyError(msg)


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"
        )

View on GitHub (pinned to 5074a0b0e1)

Solutions

1. Give --sidecar an explicit filename: --sidecar out.txt
2. Don't use --sidecar at all when writing the PDF to stdout

Example fix

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

if sidecar is None and str(output_file) == '-':
    sidecar = default_path.with_suffix('.txt')

When it happens

Trigger: options.sidecar == '\0' sentinel (CLI --sidecar with no argument) and options.output_file == '-'; checked in check_options_sidecar.

Common situations: Piping ocrmypdf output to another command (ocrmypdf ... - | ...) while also wanting a text sidecar.

Related errors

• --sidecar filename needed when output file is /dev/null or N
• --redo-ocr (or --mode redo) is not currently compatible with
• --sidecar filename needed when output file is not a path.
• --sidecar file must be different from the input and output f
• --clean is required for --unpaper-args

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