docling-project/docling · error · ImportError

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

Error message

mlx-vlm is not installed. Please install it via `pip install mlx-vlm` to use MLX VLM models.

What it means

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.

Source

Thrown at docling/models/vlm_pipeline_models/mlx_model.py:58

        self,
        enabled: bool,
        artifacts_path: Path | None,
        accelerator_options: AcceleratorOptions,
        vlm_options: InlineVlmOptions,
    ):
        self.enabled = enabled

        self.vlm_options = vlm_options
        self.max_tokens = vlm_options.max_new_tokens
        self.temperature = vlm_options.temperature

        if self.enabled:
            try:
                from mlx_vlm import generate, load, stream_generate  # type: ignore
                from mlx_vlm.prompt_utils import apply_chat_template  # type: ignore
                from mlx_vlm.utils import load_config  # type: ignore
            except ImportError:
                raise ImportError(
                    "mlx-vlm is not installed. Please install it via `pip install mlx-vlm` to use MLX VLM models."
                )

            repo_cache_folder = vlm_options.repo_id.replace("/", "--")

            self.apply_chat_template = apply_chat_template
            self.stream_generate = stream_generate

            # PARAMETERS:
            if artifacts_path is None:
                artifacts_path = self.download_models(
                    self.vlm_options.repo_id,
                    revision=self.vlm_options.revision,
                )
            elif (artifacts_path / repo_cache_folder).exists():
                artifacts_path = artifacts_path / repo_cache_folder
            else:
                # Model not found in artifacts_path - raise clear error

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Install it: pip install mlx-vlm (only meaningful on Apple Silicon macOS)
2. If on Linux/Windows, do not select the MLX engine — use the Transformers or vLLM engine instead
3. Verify the install in the same interpreter/venv Docling runs in: python -c 'import mlx_vlm'

Example fix

# before
accelerator_options.device = "mps"; vlm_options.engine = "mlx"  # ImportError
# after
# pip install mlx-vlm
vlm_options.engine = "mlx"

import importlib.util, sys

if vlm_options.engine == 'mlx':
    if sys.platform != 'darwin' or importlib.util.find_spec('mlx_vlm') is None:
        raise ImportError('MLX engine requires macOS + pip install mlx-vlm')

try:
    model = MlxVlmModel(...)
except ImportError as e:
    if 'mlx-vlm' in str(e):
        vlm_options.engine = 'transformers'
        model = None  # rebuild with the local Transformers engine
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• mlx-vlm is not installed. Please install it via `pip install
• mlx-whisper is not installed. Please install it via `pip ins
• Expected MlxVlmEngineOptions, got {type(options)}
• vllm is not installed. Please install it via `pip install vl
• The 'mail-parser' package is required to process email files

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