{"record":{"id":"5ce18a3be1c6d3fc","repo":"docling-project/docling","slug":"nemotron-ocr-is-only-supported-on-linux","errorCode":null,"errorMessage":"Nemotron OCR is only supported on Linux.","messagePattern":"Nemotron OCR is only supported on Linux\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"docling/models/stages/ocr/nemotron_ocr_model.py","lineNumber":155,"sourceCode":"                    'via `pip install \"docling[feat-ocr-nemotron]\"` on Linux x86_64 with '\n                    \"Python 3.12 and CUDA 13.x.\"\n                ) from exc\n\n            # Resolve the request language\n            language = resolve_nemotronocr_language(options.lang)\n\n            # Initialize the model\n            model_dir = self._resolve_model_dir(language, artifacts_path=artifacts_path)\n\n            self.reader = NemotronOCRV2(\n                model_dir=None if model_dir is None else str(model_dir),\n                lang=language,\n            )\n\n    @staticmethod\n    def _fail_runtime(message: str) -> None:\n        _log.error(message)\n        raise RuntimeError(message)\n\n    @classmethod\n    def validate_runtime(cls, accelerator_options: AcceleratorOptions) -> None:\n        if sys.platform != \"linux\":\n            cls._fail_runtime(\"Nemotron OCR is only supported on Linux.\")\n\n        if platform.machine() != \"x86_64\":\n            cls._fail_runtime(\"Nemotron OCR is only supported on x86_64 machines.\")\n\n        if sys.version_info[:2] != (3, 12):\n            cls._fail_runtime(\"Nemotron OCR requires Python 3.12.\")\n\n        requested_device = decide_device(accelerator_options.device)\n        if not requested_device.startswith(\"cuda\"):\n            cls._fail_runtime(\n                \"Nemotron OCR requires a CUDA accelerator. Set \"\n                \"`pipeline_options.accelerator_options.device` to CUDA or AUTO on a \"\n                \"CUDA-enabled machine.\"","sourceCodeStart":137,"sourceCodeEnd":173,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/stages/ocr/nemotron_ocr_model.py#L137-L173","documentation":"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.","triggerScenarios":"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.","commonSituations":"Developing on a Mac and deploying to Linux; trying the engine locally without a container; CI running on windows-latest runners.","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'."],"exampleFix":"# before\nfrom docling.models.stages.ocr.nemotron_ocr_model import NemotronOcrOptions\npipeline_options.ocr_options = NemotronOcrOptions()  # on macOS -> RuntimeError\n\n# after\nimport sys\nif sys.platform == \"linux\":\n    pipeline_options.ocr_options = NemotronOcrOptions()\nelse:\n    from docling.models.stages.ocr.tesseract_ocr_model import TesseractOcrOptions\n    pipeline_options.ocr_options = TesseractOcrOptions()","handlingStrategy":"validation","validationCode":"import sys\n\nuse_nemotron = sys.platform == \"linux\"\npipeline_options.ocr_options = NemotronOcrOptions() if use_nemotron else TesseractOcrOptions()","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["nemotron","ocr","platform","linux"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}