ocrmypdf/OCRmyPDF · error · BadArgsError

--sidecar filename needed when output file is /dev/null or N

Error message

--sidecar filename needed when output file is /dev/null or NUL.

What it means

Same sidecar validation, but for the case where the output file is /dev/null or NUL (Windows). With no real output path, the sidecar filename cannot be auto-derived from it.

Source

Thrown at src/ocrmypdf/_validation.py:94

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


def check_options_preprocessing(options: OcrOptions) -> None:

View on GitHub (pinned to 5074a0b0e1)

Solutions

Specify an explicit sidecar path: --sidecar text.txt

Example fix

# before
ocrmypdf --sidecar --output-file /dev/null in.pdf out.pdf
# after
ocrmypdf --sidecar text.txt --output-file /dev/null in.pdf out.pdf

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

Dry runs that keep the sidecar need an explicit --sidecar path

When it happens

Trigger: options.sidecar == '\0' and options.output_file equals os.devnull; typically from --output-file /dev/null (or NUL) plus --sidecar with no filename.

Common situations: Dry-run/verification runs that discard the PDF but still want the extracted text.

Related errors

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