{"record":{"id":"d1427e1979c44aa1","repo":"docling-project/docling","slug":"vllm-is-not-installed-please-install-it-via-pip","errorCode":null,"errorMessage":"vLLM is not installed. Please install it via `pip install vllm` to use vLLM for high-throughput VLM inference.","messagePattern":"vLLM is not installed\\. Please install it via `pip install vllm` to use vLLM for high-throughput VLM inference\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"docling/models/inference_engines/vlm/vllm_engine.py","lineNumber":131,"sourceCode":"        self.processor: Any = None\n\n        # Initialize immediately if model_config is provided\n        if self.model_config is not None:\n            self.initialize()\n\n    def initialize(self) -> None:\n        \"\"\"Initialize the vLLM engine.\"\"\"\n        if self._initialized:\n            return\n\n        _log.info(\"Initializing vLLM VLM inference engine...\")\n\n        try:\n            from transformers import AutoProcessor\n            from vllm import LLM, SamplingParams\n        except ImportError:\n            if sys.version_info < (3, 14):\n                raise ImportError(\n                    \"vLLM is not installed. Please install it via `pip install vllm` \"\n                    \"to use vLLM for high-throughput VLM inference.\"\n                )\n            else:\n                raise ImportError(\n                    \"vLLM is not installed. It is not yet available on Python 3.14.\"\n                )\n\n        # Determine device\n        supported_devices = [\n            AcceleratorDevice.CPU,\n            AcceleratorDevice.CUDA,\n            AcceleratorDevice.XPU,\n        ]\n        self.device = decide_device(\n            self.options.device or self.accelerator_options.device,\n            supported_devices=supported_devices,\n        )","sourceCodeStart":113,"sourceCodeEnd":149,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/inference_engines/vlm/vllm_engine.py#L113-L149","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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"],"exampleFix":"# before\noptions = VllmVlmEngineOptions()  # initialize() -> ImportError\n\n# after\n# terminal: pip install vllm\noptions = VllmVlmEngineOptions()","handlingStrategy":"validation","validationCode":"def vllm_available() -> bool:\n    try:\n        import vllm  # noqa: F401\n        return True\n    except ImportError:\n        return False\n\nif not vllm_available():\n    raise SystemExit('Install vLLM: pip install vllm, or switch engine_type to TRANSFORMERS/API')","typeGuard":null,"tryCatchPattern":"try:\n    engine.initialize()\nexcept ImportError as e:\n    if 'vLLM is not installed' in str(e):\n        raise SystemExit('pip install vllm to use the vLLM engine') from e\n    raise","preventionTips":["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"],"tags":["vlm","vllm","import-error","dependency"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}