{"record":{"id":"8f76c1586a3939e3","repo":"docling-project/docling","slug":"mlx-whisper-is-not-installed-please-install-it-vi","errorCode":null,"errorMessage":"mlx-whisper is not installed. Please install it via `pip install mlx-whisper` or do `uv sync --extra asr`.","messagePattern":"mlx-whisper is not installed\\. Please install it via `pip install mlx-whisper` or do `uv sync --extra asr`\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"docling/pipeline/asr_transcriber.py","lineNumber":389,"sourceCode":"class _MlxWhisperModel:\n    def __init__(\n        self,\n        enabled: bool,\n        artifacts_path: Path | None,\n        accelerator_options: AcceleratorOptions,\n        asr_options: InlineAsrMlxWhisperOptions,\n    ):\n        \"\"\"Transcriber using MLX Whisper for Apple Silicon optimization.\"\"\"\n        self.enabled = enabled\n\n        _log.info(f\"artifacts-path: {artifacts_path}\")\n        _log.info(f\"accelerator_options: {accelerator_options}\")\n\n        if self.enabled:\n            try:\n                import mlx_whisper  # type: ignore\n            except ImportError:\n                raise ImportError(\n                    \"mlx-whisper is not installed. Please install it via \"\n                    \"`pip install mlx-whisper` or do `uv sync --extra asr`.\"\n                )\n            self.asr_options = asr_options\n            self.mlx_whisper = mlx_whisper\n\n            self.device = decide_device(\n                accelerator_options.device,\n                supported_devices=asr_options.supported_devices,\n            )\n            _log.info(f\"Available device for MLX Whisper: {self.device}\")\n\n            self.model_name = asr_options.repo_id\n            _log.info(f\"loading _MlxWhisperModel({self.model_name})\")\n\n            # MLX Whisper models are loaded differently - they use HuggingFace repos\n            self.model_path = self.model_name\n","sourceCodeStart":371,"sourceCodeEnd":407,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/pipeline/asr_transcriber.py#L371-L407","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\npip install docling\n\n# after\npip install 'docling[asr]'  # includes mlx-whisper","handlingStrategy":"try-catch","validationCode":"def mlx_whisper_available() -> bool:\n    try:\n        import mlx_whisper  # noqa: F401\n        return True\n    except ImportError:\n        return False","typeGuard":null,"tryCatchPattern":"try:\n    _MlxWhisperModel(...)\nexcept ImportError as e:\n    if 'mlx-whisper' in str(e) and platform.system() == 'Darwin':\n        raise SystemExit('Install with: pip install mlx-whisper') from e\n    # fall back to standard whisper engine on non-Apple or missing MLX\n    opts.asr_options = InlineAsrWhisperOptions()","preventionTips":["Include 'docling[asr]' on macOS targets using MLX","Select the ASR engine from platform.machine()/system() at runtime instead of hardcoding MLX"],"tags":["asr","mlx","whisper","optional-dependency","apple-silicon"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}