{"record":{"id":"8bdc52a9f74d2e77","repo":"docling-project/docling","slug":"mlx-vlm-is-not-installed-please-install-it-via-p-8bdc52","errorCode":null,"errorMessage":"mlx-vlm is not installed. Please install it via `pip install mlx-vlm` to use MLX VLM models.","messagePattern":"mlx-vlm is not installed\\. Please install it via `pip install mlx-vlm` to use MLX VLM models\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"docling/models/vlm_pipeline_models/mlx_model.py","lineNumber":58,"sourceCode":"        self,\n        enabled: bool,\n        artifacts_path: Path | None,\n        accelerator_options: AcceleratorOptions,\n        vlm_options: InlineVlmOptions,\n    ):\n        self.enabled = enabled\n\n        self.vlm_options = vlm_options\n        self.max_tokens = vlm_options.max_new_tokens\n        self.temperature = vlm_options.temperature\n\n        if self.enabled:\n            try:\n                from mlx_vlm import generate, load, stream_generate  # type: ignore\n                from mlx_vlm.prompt_utils import apply_chat_template  # type: ignore\n                from mlx_vlm.utils import load_config  # type: ignore\n            except ImportError:\n                raise ImportError(\n                    \"mlx-vlm is not installed. Please install it via `pip install mlx-vlm` to use MLX VLM models.\"\n                )\n\n            repo_cache_folder = vlm_options.repo_id.replace(\"/\", \"--\")\n\n            self.apply_chat_template = apply_chat_template\n            self.stream_generate = stream_generate\n\n            # PARAMETERS:\n            if artifacts_path is None:\n                artifacts_path = self.download_models(\n                    self.vlm_options.repo_id,\n                    revision=self.vlm_options.revision,\n                )\n            elif (artifacts_path / repo_cache_folder).exists():\n                artifacts_path = artifacts_path / repo_cache_folder\n            else:\n                # Model not found in artifacts_path - raise clear error","sourceCodeStart":40,"sourceCodeEnd":76,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/vlm_pipeline_models/mlx_model.py#L40-L76","documentation":"MlxVlmModel imports mlx_vlm (generate, load, stream_generate, prompt_utils, load_config) at construction when enabled; mlx-vlm is an optional dependency and only runs on Apple Silicon macOS. A plain ImportError from the probe is re-raised with install instructions.","triggerScenarios":"Selecting the MLX engine with vlm_options while mlx_vlm is absent from the interpreter, which is the default outside a dedicated install; also fires on non-macOS platforms where MLX cannot be installed at all.","commonSituations":"Trying MLX on Linux/Windows boxes; installing mlx-vlm into a different venv than the one Docling runs in; assuming mlx-vlm is part of docling's default dependencies.","solutions":["Install it: pip install mlx-vlm (only meaningful on Apple Silicon macOS)","If on Linux/Windows, do not select the MLX engine — use the Transformers or vLLM engine instead","Verify the install in the same interpreter/venv Docling runs in: python -c 'import mlx_vlm'"],"exampleFix":"# before\naccelerator_options.device = \"mps\"; vlm_options.engine = \"mlx\"  # ImportError\n# after\n# pip install mlx-vlm\nvlm_options.engine = \"mlx\"","handlingStrategy":"validation","validationCode":"import importlib.util, sys\n\nif vlm_options.engine == 'mlx':\n    if sys.platform != 'darwin' or importlib.util.find_spec('mlx_vlm') is None:\n        raise ImportError('MLX engine requires macOS + pip install mlx-vlm')","typeGuard":null,"tryCatchPattern":"try:\n    model = MlxVlmModel(...)\nexcept ImportError as e:\n    if 'mlx-vlm' in str(e):\n        vlm_options.engine = 'transformers'\n        model = None  # rebuild with the local Transformers engine\n    else:\n        raise","preventionTips":["Gate MLX usage behind a platform check (darwin + arm64)","Install mlx-vlm in the exact venv Docling runs in","Keep an engine fallback configured for cross-platform deployments"],"tags":["mlx","import-error","optional-dependency","apple-silicon"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}