docling-project/docling · error · ImportError

vLLM is not installed. Please install it via `pip install vl

Q: What causes "vLLM is not installed. Please install it via `pip install vllm` to use vLLM for high-throughput VLM inference." in docling-project/docling?

pip install vllm in the active environment

Error message

vLLM is not installed. Please install it via `pip install vllm` to use vLLM for high-throughput VLM inference.

What it means

VllmVlmEngine.initialize() imports vllm (and transformers AutoProcessor) at init time. On Python < 3.14, a missing vllm package is re-raised as ImportError with install instructions, because vLLM is an optional heavyweight dependency needed for high-throughput VLM inference.

Source

Thrown at docling/models/inference_engines/vlm/vllm_engine.py:131

        self.processor: Any = None

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

    def initialize(self) -> None:
        """Initialize the vLLM engine."""
        if self._initialized:
            return

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

        try:
            from transformers import AutoProcessor
            from vllm import LLM, SamplingParams
        except ImportError:
            if sys.version_info < (3, 14):
                raise ImportError(
                    "vLLM is not installed. Please install it via `pip install vllm` "
                    "to use vLLM for high-throughput VLM inference."
                )
            else:
                raise ImportError(
                    "vLLM is not installed. It is not yet available on Python 3.14."
                )

        # Determine device
        supported_devices = [
            AcceleratorDevice.CPU,
            AcceleratorDevice.CUDA,
            AcceleratorDevice.XPU,
        ]
        self.device = decide_device(
            self.options.device or self.accelerator_options.device,
            supported_devices=supported_devices,
        )

View on GitHub (pinned to 61d76f1ff3)

Solutions

pip install vllm in the active environment
Verify the install: python -c 'import vllm; print(vllm.__version__)'
If you do not need vLLM throughput, switch the engine type to TRANSFORMERS or API instead of installing it

Example fix

# before
options = VllmVlmEngineOptions()  # initialize() -> ImportError

# after
# terminal: pip install vllm
options = VllmVlmEngineOptions()

Defensive patterns

Strategy: validation

Validate before calling

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

if not vllm_available():
    raise SystemExit('Install vLLM: pip install vllm, or switch engine_type to TRANSFORMERS/API')

Try / catch

try:
    engine.initialize()
except ImportError as e:
    if 'vLLM is not installed' in str(e):
        raise SystemExit('pip install vllm to use the vLLM engine') from e
    raise

Prevention

Add vllm to dependencies for deployments using the VLLM engine type
Probe 'import vllm' at startup rather than failing on the first batch
Document the vLLM install as an explicit extra so fresh environments do not silently lack it

When it happens

Trigger: Creating a VLM pipeline with VlmEngineType.VLLM and calling initialize() (directly or lazily via predict_batch) in an environment where vllm is not installed and sys.version_info < (3, 14).

Common situations: Fresh docling install without the vLLM extra; running on platforms where vLLM wheels are unavailable; forgetting that vLLM must be installed separately from docling-core.

Related errors

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