What causes "Nemotron OCR requires Python 3.12." in docling-project/docling?

Create a Python 3.12 environment (pyenv install 3.12 / conda create -n nem python=3.12) and install docling with the extra there.

docling-project/docling · error · RuntimeError

Nemotron OCR requires Python 3.12.

Error message

Nemotron OCR requires Python 3.12.

What it means

Nemotron OCR is pinned to Python 3.12 because its optional dependency wheels (docling[feat-ocr-nemotron]) are published only for CPython 3.12. validate_runtime compares sys.version_info[:2] to (3,12) and raises RuntimeError on any other minor version, even if the import somehow succeeded.

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

Create a Python 3.12 environment (pyenv install 3.12 / conda create -n nem python=3.12) and install docling with the extra there.
If you cannot change interpreter version, use another OCR engine via pipeline_options.ocr_options.
Pin the environment (Dockerfile FROM python:3.12) so the constraint is enforced by tooling, not by this error.

Example fix

# before (Python 3.11 env)
pipeline_options.ocr_options = NemotronOcrOptions()  # RuntimeError: requires Python 3.12

# after (terminal)
pyenv install 3.12.7 && pyenv local 3.12.7
pip install "docling[feat-ocr-nemotron]"

Defensive patterns

Strategy: validation

Validate before calling

import sys

assert sys.version_info[:2] == (3, 12), "Nemotron OCR requires Python 3.12"

Prevention

Run the Nemotron pipeline in a pinned python:3.12 environment (Docker or pyenv).
Assert the interpreter version at startup before selecting the engine.
Keep the Nemotron-using service isolated from apps on other Python versions.

When it happens

Trigger: Running the Nemotron OCR stage under Python 3.10/3.11/3.13/3.14 — the version check fails during model construction before any work is done.

Common situations: Default system Python of a distro not being 3.12; pyenv/conda environments on 3.11 or 3.13; docling dropped into an existing app running a different Python.

Related errors

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