{"record":{"id":"6e57e6aca7fa95de","repo":"docling-project/docling","slug":"nemotron-ocr-requires-a-cuda-accelerator-set-pip","errorCode":null,"errorMessage":"Nemotron OCR requires a CUDA accelerator. Set `pipeline_options.accelerator_options.device` to CUDA or AUTO on a CUDA-enabled machine.","messagePattern":"Nemotron OCR requires a CUDA accelerator\\. Set `pipeline_options\\.accelerator_options\\.device` to CUDA or AUTO on a CUDA-enabled machine\\.","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":"Nemotron OCR requires GPU acceleration; validate_runtime inspects accelerator_options.device and raises RuntimeError unless it resolves to CUDA (directly or via AUTO on a CUDA machine). CPU, MPS, or an explicit non-CUDA device are rejected at construction time because the Nemotron checkpoints only run on CUDA 13.x.","triggerScenarios":"Setting pipeline_options.accelerator_options.device = AcceleratorDevice.CPU (the docling default on many installs) while enabling NemotronOcrOptions; or AUTO on a machine with no NVIDIA GPU so it resolves to CPU.","commonSituations":"Default CPU pipeline options on GPU-less machines; users who copied a CPU config for other docling stages; GPU present but device left at CPU in a saved config.","solutions":["Set accelerator_options.device = AcceleratorDevice.CUDA (or AUTO on a CUDA machine) before building the pipeline.","Ensure an NVIDIA GPU with CUDA 13.x drivers is actually available (nvidia-smi).","If no NVIDIA GPU exists, use a CUDA-capable host/container or fall back to a CPU-capable OCR engine (Tesseract, RapidOCR onnxruntime)."],"exampleFix":"# before\nfrom docling.datamodel.accelerator_options import AcceleratorDevice, AcceleratorOptions\npipeline_options.accelerator_options = AcceleratorOptions(device=AcceleratorDevice.CPU)\npipeline_options.ocr_options = NemotronOcrOptions()  # RuntimeError\n\n# after\npipeline_options.accelerator_options = AcceleratorOptions(device=AcceleratorDevice.CUDA)\npipeline_options.ocr_options = NemotronOcrOptions()","handlingStrategy":"validation","validationCode":"from docling.datamodel.accelerator_options import AcceleratorDevice, AcceleratorOptions\n\noptions = AcceleratorOptions(device=AcceleratorDevice.CUDA)  # required for Nemotron","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set accelerator_options.device to CUDA (or AUTO on GPU hosts) whenever Nemotron OCR is enabled.","Verify nvidia-smi works in the target environment before deploying.","Centralize accelerator settings in config so CPU defaults cannot silently reach the Nemotron pipeline."],"tags":["nemotron","ocr","cuda","accelerator","gpu"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}