What causes "vLLM is not installed. It is not yet available on Python 3.14." in docling-project/docling?

Run the workload on Python 3.10-3.13 where vLLM wheels exist, then pip install vllm

docling-project/docling · error · ImportError

vLLM is not installed. It is not yet available on Python 3.1

Error message

vLLM is not installed. It is not yet available on Python 3.14.

What it means

VllmVlmEngine.initialize() cannot import vllm and detects Python 3.14 or newer. The message differs from the generic one because vLLM simply has no releases for Python 3.14 yet — installing it is not possible, so the fix is environmental, not a pip command.

Source

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

    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,
        )
        _log.info(f"Using device: {self.device}")

        # 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

View on GitHub (pinned to 61d76f1ff3)

Solutions

Run the workload on Python 3.10-3.13 where vLLM wheels exist, then pip install vllm
Or use the TRANSFORMERS engine for local inference on Python 3.14
Or use the API engine with a remote vLLM server so the client machine's Python version does not matter

Example fix

# before (Python 3.14 host)
options = VllmVlmEngineOptions()  # initialize() -> ImportError: not available on 3.14

# after
# use a 3.12 environment:
# pyenv install 3.12 && pyenv local 3.12 && pip install vllm docling
options = VllmVlmEngineOptions()

Defensive patterns

Strategy: validation

Validate before calling

import sys

if sys.version_info >= (3, 14):
    raise SystemExit(
        'vLLM is unavailable on Python 3.14+; use Python 3.10-3.13, '
        'the TRANSFORMERS engine, or the API engine against a remote vLLM server'
    )

Try / catch

try:
    engine.initialize()
except ImportError as e:
    if 'Python 3.14' in str(e):
        raise SystemExit('Run on Python 3.13 or older for the vLLM engine, or use TRANSFORMERS/API') from e
    raise

Prevention

Pin the deployment interpreter to a Python version supported by vLLM (3.10-3.13)
Add a sys.version_info guard before building VLLM pipelines
For newest-Python hosts, use the API engine against a vLLM server running elsewhere

When it happens

Trigger: Running the VLLM engine on sys.version_info >= (3, 14) where the vllm import fails; the version check inside the ImportError handler produces this dedicated message.

Common situations: Upgrading the Python interpreter to 3.14 while keeping a vLLM-based pipeline; new projects bootstrapped on the newest Python where vLLM wheels do not exist yet.

Related errors

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