What causes "Nemotron OCR is only supported on Linux." in docling-project/docling?

Run docling with Nemotron OCR inside a Linux container (e.g. python:3.12-slim or a CUDA base image) matching the other requirements (x86_64, Python 3.12, CUDA 13.x).

docling-project/docling · error · RuntimeError

Nemotron OCR is only supported on Linux.

Error message

Nemotron OCR is only supported on Linux.

What it means

NemotronOCR validates the host platform before use: sys.platform must be 'linux'. On any other OS (macOS, Windows) a RuntimeError is raised via _fail_runtime, which also logs the message. The restriction exists because the upstream nemotron_ocr package and its CUDA 13.x dependencies are only published for Linux.

Source

Thrown at docling/models/stages/ocr/nemotron_ocr_model.py:155

                    'via `pip install "docling[feat-ocr-nemotron]"` on Linux x86_64 with '
                    "Python 3.12 and CUDA 13.x."
                ) from exc

            # Resolve the request language
            language = resolve_nemotronocr_language(options.lang)

            # Initialize the model
            model_dir = self._resolve_model_dir(language, artifacts_path=artifacts_path)

            self.reader = NemotronOCRV2(
                model_dir=None if model_dir is None else str(model_dir),
                lang=language,
            )

    @staticmethod
    def _fail_runtime(message: str) -> None:
        _log.error(message)
        raise RuntimeError(message)

    @classmethod
    def validate_runtime(cls, accelerator_options: AcceleratorOptions) -> None:
        if sys.platform != "linux":
            cls._fail_runtime("Nemotron OCR is only supported on Linux.")

        if platform.machine() != "x86_64":
            cls._fail_runtime("Nemotron OCR is only supported on x86_64 machines.")

        if sys.version_info[:2] != (3, 12):
            cls._fail_runtime("Nemotron OCR requires Python 3.12.")

        requested_device = decide_device(accelerator_options.device)
        if not requested_device.startswith("cuda"):
            cls._fail_runtime(
                "Nemotron OCR requires a CUDA accelerator. Set "
                "`pipeline_options.accelerator_options.device` to CUDA or AUTO on a "
                "CUDA-enabled machine."

View on GitHub (pinned to 61d76f1ff3)

Solutions

Run docling with Nemotron OCR inside a Linux container (e.g. python:3.12-slim or a CUDA base image) matching the other requirements (x86_64, Python 3.12, CUDA 13.x).
On non-Linux hosts, select a different OCR engine via pipeline_options.ocr_options (Tesseract, EasyOCR, RapidOCR).
Gate engine choice in code: pick Nemotron only when sys.platform == 'linux'.

Example fix

# before
from docling.models.stages.ocr.nemotron_ocr_model import NemotronOcrOptions
pipeline_options.ocr_options = NemotronOcrOptions()  # on macOS -> RuntimeError

# after
import sys
if sys.platform == "linux":
    pipeline_options.ocr_options = NemotronOcrOptions()
else:
    from docling.models.stages.ocr.tesseract_ocr_model import TesseractOcrOptions
    pipeline_options.ocr_options = TesseractOcrOptions()

Defensive patterns

Strategy: validation

Validate before calling

import sys

use_nemotron = sys.platform == "linux"
pipeline_options.ocr_options = NemotronOcrOptions() if use_nemotron else TesseractOcrOptions()

Prevention

Select OCR engines per platform in a small factory function instead of hardcoding one option set.
On non-Linux dev machines, test the Nemotron path inside a Linux/CUDA container.
Add a smoke test that builds the pipeline on the target platform to catch gating mistakes early.

When it happens

Trigger: Constructing/running the Nemotron OCR stage on macOS or Windows — the platform check in validate_runtime fires before any model loading, regardless of whether the package is importable.

Common situations: Developing on a Mac and deploying to Linux; trying the engine locally without a container; CI running on windows-latest runners.

Related errors

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/5ce18a3be1c6d3fc. Report an issue: GitHub.