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 on Apple Silicon.

What it means

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.

Source

Thrown at docling/models/inference_engines/vlm/mlx_engine.py:89

        self.stream_generate: Any = None

        # Initialize immediately if model_config is provided
        if self.model_config is not None:
            self.initialize()

    def initialize(self) -> None:
        """Initialize the MLX model and processor."""
        if self._initialized:
            return

        _log.info("Initializing MLX VLM inference engine...")

        try:
            from mlx_vlm import load, stream_generate
            from mlx_vlm.prompt_utils import apply_chat_template
            from mlx_vlm.utils import load_config
        except ImportError:
            raise ImportError(
                "mlx-vlm is not installed. Please install it via `pip install mlx-vlm` "
                "to use MLX VLM models on Apple Silicon."
            )

        self.apply_chat_template = apply_chat_template  # type: ignore[assignment]
        self.stream_generate = stream_generate  # type: ignore[assignment]

        # Load model if model_config is provided
        if self.model_config is not None and self.model_config.repo_id is not None:
            repo_id = self.model_config.repo_id
            revision = self.model_config.revision or "main"

            _log.info(f"Loading MLX model {repo_id} (revision: {revision})")
            self._load_model_for_repo(repo_id, revision=revision)

        self._initialized = True
        _log.info("MLX runtime initialized")

View on GitHub (pinned to 61d76f1ff3)

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

Example fix

# before
options = MlxVlmEngineOptions()  # fails at initialize(): mlx-vlm not installed

# after
# terminal: pip install mlx-vlm
options = MlxVlmEngineOptions()

Defensive patterns

Strategy: validation

Validate before calling

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

if not mlx_available():
    raise SystemExit('Install mlx-vlm (Apple Silicon only) or switch to the TRANSFORMERS engine')

Try / catch

try:
    engine.initialize()
except ImportError as e:
    if 'mlx-vlm' in str(e):
        raise SystemExit('pip install mlx-vlm (Apple Silicon macOS only)') from e
    raise

Prevention

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

When it happens

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

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

Related errors

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