docling-project/docling · error · ImportError

whisper is not installed. Unfortunately its dependencies are

Error message

whisper is not installed. Unfortunately its dependencies are not yet available for Python 3.14.

What it means

Same missing-whisper condition as the sibling error, but on Python 3.14+ the message changes: openai-whisper's dependencies are not yet available for 3.14, so installing it is not a viable fix. The library deliberately distinguishes this so users on 3.14 do not chase a broken install.

Source

Thrown at docling/pipeline/asr_transcriber.py:215

        asr_options: InlineAsrNativeWhisperOptions,
    ):
        """Transcriber using native Whisper."""
        self.enabled = enabled

        _log.info(f"artifacts-path: {artifacts_path}")
        _log.info(f"accelerator_options: {accelerator_options}")

        if self.enabled:
            try:
                import whisper  # type: ignore
            except ImportError:
                if sys.version_info < (3, 14):
                    raise ImportError(
                        "whisper is not installed. Please install it via "
                        "`pip install openai-whisper` or do `uv sync --extra asr`."
                    )
                else:
                    raise ImportError(
                        "whisper is not installed. Unfortunately its dependencies "
                        "are not yet available for Python 3.14."
                    )

            self.asr_options = asr_options
            self.max_tokens = asr_options.max_new_tokens

            self.device = decide_device(
                accelerator_options.device,
                supported_devices=asr_options.supported_devices,
            )
            _log.info(f"Available device for Whisper: {self.device}")

            self.model_name = asr_options.repo_id
            _log.info(f"loading _NativeWhisperModel({self.model_name})")
            distil_checkpoint = _DISTIL_WHISPER_OPENAI_CHECKPOINTS.get(self.model_name)
            if distil_checkpoint is not None:
                from huggingface_hub import hf_hub_download

View on GitHub (pinned to 61d76f1ff3)

Solutions

Run on a supported Python (3.10-3.13) — e.g. switch the docker base image or pyenv/uv version
Use a different ASR engine that supports your Python (whisper_s2t via InlineAsrWhisperS2TOptions, if installable)
Pin the project to docling versions once openai-whisper publishes 3.14-compatible dependencies

Example fix

# before
# Dockerfile
FROM python:3.14

# after
FROM python:3.12

Defensive patterns

Strategy: validation

Validate before calling

import sys

if sys.version_info >= (3, 14):
    raise RuntimeError('Native whisper ASR requires Python <= 3.13; select another ASR engine or pin Python')

Prevention

Pin CI and production images to a supported Python (3.10-3.13) when using native whisper
Gate engine selection on sys.version_info so 3.14 environments fall back to whisper_s2t or disable ASR

When it happens

Trigger: Running the whisper ASR transcriber enabled on CPython 3.14 or newer in any environment — the import always fails because the wheel ecosystem (e.g. triton/tokenizer builds openai-whisper pins) lacks 3.14 support at this docling version.

Common situations: New Python release adopted early in CI images or dev machines; docker base image upgraded to python:3.14 while using docling's native Whisper engine.

Related errors

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