{"record":{"id":"c63cd18ea3e5e737","repo":"docling-project/docling","slug":"mlx-vlm-is-not-installed-please-install-it-via-p","errorCode":null,"errorMessage":"mlx-vlm is not installed. Please install it via `pip install mlx-vlm` to use MLX VLM models on Apple Silicon.","messagePattern":"mlx-vlm is not installed\\. Please install it via `pip install mlx-vlm` to use MLX VLM models on Apple Silicon\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"docling/models/inference_engines/vlm/mlx_engine.py","lineNumber":89,"sourceCode":"        self.stream_generate: Any = None\n\n        # Initialize immediately if model_config is provided\n        if self.model_config is not None:\n            self.initialize()\n\n    def initialize(self) -> None:\n        \"\"\"Initialize the MLX model and processor.\"\"\"\n        if self._initialized:\n            return\n\n        _log.info(\"Initializing MLX VLM inference engine...\")\n\n        try:\n            from mlx_vlm import load, stream_generate\n            from mlx_vlm.prompt_utils import apply_chat_template\n            from mlx_vlm.utils import load_config\n        except ImportError:\n            raise ImportError(\n                \"mlx-vlm is not installed. Please install it via `pip install mlx-vlm` \"\n                \"to use MLX VLM models on Apple Silicon.\"\n            )\n\n        self.apply_chat_template = apply_chat_template  # type: ignore[assignment]\n        self.stream_generate = stream_generate  # type: ignore[assignment]\n\n        # Load model if model_config is provided\n        if self.model_config is not None and self.model_config.repo_id is not None:\n            repo_id = self.model_config.repo_id\n            revision = self.model_config.revision or \"main\"\n\n            _log.info(f\"Loading MLX model {repo_id} (revision: {revision})\")\n            self._load_model_for_repo(repo_id, revision=revision)\n\n        self._initialized = True\n        _log.info(\"MLX runtime initialized\")\n","sourceCodeStart":71,"sourceCodeEnd":107,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/inference_engines/vlm/mlx_engine.py#L71-L107","documentation":"MlxVlmEngine.initialize() imports mlx_vlm (load, stream_generate, apply_chat_template, load_config) at init time, and the ImportError is re-raised with install instructions when the package is absent. MLX support is an optional dependency because mlx-vlm only runs on Apple Silicon macOS.","triggerScenarios":"Using a VLM pipeline with VlmEngineType.MLX on a machine (or virtualenv) where mlx-vlm is not installed; calling predict_batch (which lazily calls initialize()) without ever importing mlx_vlm.","commonSituations":"Running the MLX engine on Linux/Windows where mlx-vlm cannot be installed; installing docling without MLX extras; a CI environment that lacks the Apple-Silicon-only wheel.","solutions":["pip install mlx-vlm in the active environment","Confirm you are on Apple Silicon (M-series) macOS; on Linux/Windows use the TRANSFORMERS or VLLM engine instead","If using a managed env (uv/poetry), add mlx-vlm to the project dependencies so it is always present"],"exampleFix":"# before\noptions = MlxVlmEngineOptions()  # fails at initialize(): mlx-vlm not installed\n\n# after\n# terminal: pip install mlx-vlm\noptions = MlxVlmEngineOptions()","handlingStrategy":"validation","validationCode":"def mlx_available() -> bool:\n    try:\n        import mlx_vlm  # noqa: F401\n        return True\n    except ImportError:\n        return False\n\nif not mlx_available():\n    raise SystemExit('Install mlx-vlm (Apple Silicon only) or switch to the TRANSFORMERS engine')","typeGuard":null,"tryCatchPattern":"try:\n    engine.initialize()\nexcept ImportError as e:\n    if 'mlx-vlm' in str(e):\n        raise SystemExit('pip install mlx-vlm (Apple Silicon macOS only)') from e\n    raise","preventionTips":["Add mlx-vlm to the dependency set of any deployment that uses the MLX engine","Gate MLX pipelines on platform.system() == 'Darwin' and arm64 hardware","Fail fast at startup with an import probe instead of at first inference"],"tags":["vlm","mlx","import-error","dependency","apple-silicon"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}