opendatalab/MinerU · error · EnvironmentError

mlx-engine backend is only supported on macOS 13.5+ with App

Error message

mlx-engine backend is only supported on macOS 13.5+ with Apple Silicon.

What it means

Raised on the mlx-engine branch (vlm_analyze.py) when is_mac_os_version_supported() reports the machine is not macOS 13.5+ on Apple Silicon. MLX (and therefore MinerU's mlx-engine backend) only exists on that platform, so the check fails fast before attempting load_mlx_model.

Source

Thrown at mineru/backend/vlm/vlm_analyze.py:111

                        dtype_key = "dtype"
                    else:
                        dtype_key = "torch_dtype"
                    device = get_device()
                    model = Qwen2VLForConditionalGeneration.from_pretrained(
                        model_path,
                        device_map={"": device},
                        **{dtype_key: "auto"},  # type: ignore
                    )
                    processor = AutoProcessor.from_pretrained(
                        model_path,
                        use_fast=True,
                    )
                    if batch_size == 0:
                        batch_size = set_default_batch_size()
                elif backend == "mlx-engine":
                    mlx_supported = is_mac_os_version_supported()
                    if not mlx_supported:
                        raise EnvironmentError("mlx-engine backend is only supported on macOS 13.5+ with Apple Silicon.")
                    from mineru_vl_utils.mlx_compat import load_mlx_model
                    model, processor = load_mlx_model(model_path)
                else:
                    if os.getenv('OMP_NUM_THREADS') is None:
                        os.environ["OMP_NUM_THREADS"] = "1"

                    if backend == "vllm-engine":
                        try:
                            import vllm
                        except ImportError:
                            raise ImportError("Please install vllm to use the vllm-engine backend.")

                        kwargs = mod_kwargs_by_device_type(kwargs, vllm_mode="sync_engine")

                        if "compilation_config" in kwargs:
                            if isinstance(kwargs["compilation_config"], str):
                                try:
                                    kwargs["compilation_config"] = json.loads(kwargs["compilation_config"])

View on GitHub (pinned to 4fe4bde114)

Solutions

1. On Linux/Windows with NVIDIA GPU use vllm-engine or lmdeploy-engine; on Apple Silicon update macOS to >=13.5.
2. On Intel Macs use the transformers backend (CPU) or an http-client backend to a remote GPU server.
3. Make backend selection platform-conditional in your launch script.

Example fix

# before (Linux)
run(backend="mlx-engine", ...)  # EnvironmentError

# after
import platform
backend = "mlx-engine" if platform.system() == "Darwin" else "vllm-engine"
run(backend=backend, ...)

import platform

def mlx_platform_ok() -> bool:
    if platform.system() != "Darwin":
        return False
    return tuple(int(x) for x in platform.mac_ver()[0].split(".")[:2]) >= (13, 5)

import platform

def can_use_mlx_engine() -> bool:
    return platform.system() == "Darwin" and platform.machine() == "arm64"

try:
    vlm_analyze(..., backend="mlx-engine")
except EnvironmentError as e:
    if "mlx-engine" in str(e):
        vlm_analyze(..., backend="transformers")  # portable fallback
    else:
        raise

When it happens

Trigger: backend='mlx-engine' on Linux/Windows, on an Intel Mac, or on a macOS version older than 13.5.

Common situations: Sharing one config across a mixed fleet (Linux server + Mac laptop); CI runners on Linux with a config authored on a Mac; older macOS that cannot run MLX.

Related errors

• backend={backend} requires server_url
• Unsupported operating system.
• Please install transformers to use the transformers backend.
• Unsupported lmdeploy backend: {lm_backend}
• Invalid backend. Allowed values: {allowed_values}

AI-assisted analysis of opendatalab/MinerU@4fe4bde114 (2026-08-14). Data as JSON: /api/errors/c0ac6693f4d658a9. Report an issue: GitHub.