opendatalab/MinerU · error · ImportError

Please install vllm to use the vllm-engine backend.

Error message

Please install vllm to use the vllm-engine backend.

What it means

Raised on the vllm-engine branch (vlm_analyze.py) when `import vllm` fails. The synchronous vllm-engine backend constructs vllm.LLM(**kwargs), so vllm must be importable; the try/except converts the raw ImportError into guidance to install vllm.

Source

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

                        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"])
                                except json.JSONDecodeError:
                                    logger.warning(
                                        f"Failed to parse compilation_config as JSON: {kwargs['compilation_config']}")
                                    del kwargs["compilation_config"]
                        if "gpu_memory_utilization" not in kwargs:
                            kwargs["gpu_memory_utilization"] = set_default_gpu_memory_utilization()
                        if "model" not in kwargs:
                            kwargs["model"] = model_path
                        if enable_custom_logits_processors() and ("logits_processors" not in kwargs):
                            from mineru_vl_utils import MinerULogitsProcessor
                            kwargs["logits_processors"] = [MinerULogitsProcessor]

View on GitHub (pinned to 4fe4bde114)

Solutions

1. pip install vllm (matching your torch/CUDA and Python version).
2. If installed, run python -c "import vllm" to see the true error and align torch/vllm versions.
3. Without a GPU stack, use transformers backend or a remote http-client backend.

Example fix

# before
run(backend="vllm-engine", ...)  # ImportError

# after
pip install vllm  # or: pip install -e "mineru[vllm]" per docs
run(backend="vllm-engine", ...)

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

if not vllm_available():
    backend = "transformers"  # or "http-client" to remote GPU server

try:
    vlm_analyze(..., backend="vllm-engine")
except ImportError as e:
    if "install vllm" in str(e):
        raise RuntimeError("environment missing vllm; deploy GPU image or switch backend") from e
    raise

When it happens

Trigger: backend='vllm-engine' without vllm installed; vllm installed but failing to import due to CUDA/torch version mismatch; vllm built for a different Python version.

Common situations: Default lightweight install plus GPU backend selected; torch upgraded independently breaking vllm's compiled extensions; wrong-architecture wheels (e.g. CPU wheel of vllm).

Related errors

• Please install vllm to use the vllm-async-engine backend.
• Please install vllm to use the vllm-async-engine backend.
• Please install lmdeploy to use the lmdeploy-engine backend.
• Please install transformers to use the transformers backend.
• CUDA is not available.

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