docling-project/docling · error · ImportError

whisper is not installed. Please install it via `pip install

Error message

whisper is not installed. Please install it via `pip install openai-whisper` or do `uv sync --extra asr`.

What it means

The native-Whisper ASR transcriber (_WhisperModel) imports the optional `whisper` package (openai-whisper) when enabled; on Python < 3.14 the ImportError is re-raised with install instructions. It is a missing-optional-dependency error: docling's ASR support ships behind the `asr` extra rather than the base install.

Source

Thrown at docling/pipeline/asr_transcriber.py:210

    def __init__(
        self,
        enabled: bool,
        artifacts_path: Path | None,
        accelerator_options: AcceleratorOptions,
        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}")

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Install the ASR extra: uv sync --extra asr (or pip install 'docling[asr]')
2. Or install the engine directly: pip install openai-whisper
3. Or disable ASR / switch asr_options to an engine whose deps you have (e.g. mlx-whisper on Apple Silicon)

Example fix

# before
pip install docling

# after
pip install 'docling[asr]'

def whisper_available() -> bool:
    try:
        import whisper  # noqa: F401
        return True
    except ImportError:
        return False

try:
    pipeline = InlineAsrPipeline(...)
except ImportError as e:
    if 'openai-whisper' in str(e):
        subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'openai-whisper'])
        pipeline = InlineAsrPipeline(...)
    else:
        raise

When it happens

Trigger: Enabling InlineAsrPipeline / AsrOptions with the default whisper engine in an environment where `import whisper` fails — i.e. docling installed without the asr extra. Raised from the transcriber constructor, so it fires at pipeline build time, not per-document.

Common situations: Running audio transcription (do_rotate=False + inline ASR on audio files) after `pip install docling` instead of `pip install 'docling[asr]'`; slim installs (docling-slim) that never bundle ASR deps.

Related errors

• mlx-whisper is not installed. Please install it via `pip ins
• whisper_s2t is not installed. Please install it via `pip ins
• The 'mail-parser' package is required to process email files
• The 'beautifulsoup4' package is required to process HTML fil
• The 'pylatexenc' package is required to process LaTeX files.

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