docling-project/docling · error · ImportError

mlx-whisper is not installed. Please install it via `pip ins

Error message

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

What it means

The MLX-Whisper transcriber (_MlxWhisperModel), used for Apple-Silicon-optimized ASR, imports the optional `mlx_whisper` package when enabled and re-raises ImportError with install guidance if absent. Unlike native whisper, there is no Python-version carve-out — the dependency is simply missing.

Source

Thrown at docling/pipeline/asr_transcriber.py:389

class _MlxWhisperModel:
    def __init__(
        self,
        enabled: bool,
        artifacts_path: Path | None,
        accelerator_options: AcceleratorOptions,
        asr_options: InlineAsrMlxWhisperOptions,
    ):
        """Transcriber using MLX Whisper for Apple Silicon optimization."""
        self.enabled = enabled

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

        if self.enabled:
            try:
                import mlx_whisper  # type: ignore
            except ImportError:
                raise ImportError(
                    "mlx-whisper is not installed. Please install it via "
                    "`pip install mlx-whisper` or do `uv sync --extra asr`."
                )
            self.asr_options = asr_options
            self.mlx_whisper = mlx_whisper

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

            self.model_name = asr_options.repo_id
            _log.info(f"loading _MlxWhisperModel({self.model_name})")

            # MLX Whisper models are loaded differently - they use HuggingFace repos
            self.model_path = self.model_name

View on GitHub (pinned to 61d76f1ff3)

Solutions

Install the asr extra: uv sync --extra asr (or pip install 'docling[asr]')
Or install directly: pip install mlx-whisper (macOS Apple Silicon only)
On non-Apple hardware, switch asr_options to the standard whisper engine instead

Example fix

# before
pip install docling

# after
pip install 'docling[asr]'  # includes mlx-whisper

Defensive patterns

Strategy: try-catch

Validate before calling

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

Try / catch

try:
    _MlxWhisperModel(...)
except ImportError as e:
    if 'mlx-whisper' in str(e) and platform.system() == 'Darwin':
        raise SystemExit('Install with: pip install mlx-whisper') from e
    # fall back to standard whisper engine on non-Apple or missing MLX
    opts.asr_options = InlineAsrWhisperOptions()

Prevention

Include 'docling[asr]' on macOS targets using MLX
Select the ASR engine from platform.machine()/system() at runtime instead of hardcoding MLX

When it happens

Trigger: Selecting the mlx-whisper engine via InlineAsrMlxWhisperOptions (or a default that resolves to it) in an environment without mlx-whisper installed; constructor-time failure when the transcriber is instantiated with enabled=True.

Common situations: Apple Silicon users enabling the MLX backend after a base `pip install docling`; CI runners that are Linux (mlx is macOS-only) while config hardcodes the MLX engine.

Related errors

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