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

Use an x86_64 Linux environment — an x86 container/host or an AMD64 cloud instance with CUDA 13.x and Python 3.12.

docling-project/docling · error · RuntimeError

Nemotron OCR is only supported on x86_64 machines.

Error message

Nemotron OCR is only supported on x86_64 machines.

What it means

validate_runtime checks platform.machine() and requires 'x86_64'. On ARM machines (Apple Silicon, AWS Graviton, ARM devboards) the Nemotron OCR stage raises RuntimeError immediately, since upstream wheels/CUDA 13.x support only x86_64. The check runs before model download or inference.

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

Use an x86_64 Linux environment — an x86 container/host or an AMD64 cloud instance with CUDA 13.x and Python 3.12.
On ARM, choose a portable OCR engine instead (Tesseract, EasyOCR with CPU, RapidOCR onnxruntime).
Check `python -c "import platform; print(platform.machine())"` before selecting the engine.

Example fix

# before
pipeline_options.ocr_options = NemotronOcrOptions()  # on aarch64 -> RuntimeError

# after
import platform
if platform.machine() == "x86_64" and sys.platform == "linux":
    pipeline_options.ocr_options = NemotronOcrOptions()
else:
    pipeline_options.ocr_options = RapidOcrOptions()

Defensive patterns

Strategy: validation

Validate before calling

import platform, sys

def nemotron_supported() -> bool:
    return sys.platform == "linux" and platform.machine() == "x86_64"

Prevention

Check platform.machine() in your engine-selection logic, not just the OS.
Beware ARM Linux containers on Apple Silicon — they pass the Linux check but fail x86_64.
Document the host requirements in your deployment config so provisioning matches them.

When it happens

Trigger: Enabling NemotronOcrOptions on aarch64/ARM64 hosts, including Apple Silicon Macs (even inside a Linux VM on ARM) and ARM cloud instances.

Common situations: M1/M2/M3 Macs; Graviton-based EC2/CLOUD instances; Raspberry Pi-class boards; ARM CI runners.

Related errors

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