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

Run Docling under Python 3.10–3.13 (e.g. uv venv --python 3.12) to use the vLLM engine

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

Variant of the vllm import guard that fires only on Python 3.14+: at the time of this check, vLLM had not published support for Python 3.14, so Docling reports unavailability explicitly instead of a confusing missing-module error. This is an environment constraint, not a pip-fixable miss.

Source

Thrown at docling/models/vlm_pipeline_models/vllm_model.py:118

        self.processor = None  # used for CHAT templating in formulate_prompt()
        self.device = "cpu"
        self.max_new_tokens = vlm_options.max_new_tokens
        self.temperature = vlm_options.temperature

        if not self.enabled:
            return

        from transformers import AutoProcessor

        try:
            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`."
                )
            else:
                raise ImportError(
                    "vllm is not installed. It is not yet available on Python 3.14."
                )

        # Device selection
        self.device = decide_device(
            accelerator_options.device, supported_devices=vlm_options.supported_devices
        )
        _log.debug(f"Available device for VLM: {self.device}")

        # Resolve artifacts path / cache folder
        repo_cache_folder = vlm_options.repo_id.replace("/", "--")
        if artifacts_path is None:
            artifacts_path = self.download_models(
                self.vlm_options.repo_id, revision=self.vlm_options.revision
            )
        elif (artifacts_path / repo_cache_folder).exists():
            artifacts_path = artifacts_path / repo_cache_folder
        else:

View on GitHub (pinned to 61d76f1ff3)

Solutions

Run Docling under Python 3.10–3.13 (e.g. uv venv --python 3.12) to use the vLLM engine
Stay on 3.14 but switch VlmOptions to the Transformers or MLX engine, which do not need vllm
Recheck periodically: once vllm ships 3.14 wheels, upgrading vllm removes this guard

Example fix

# before: system python is 3.14
vlm_options.engine = "vllm"  # ImportError: not available on 3.14
# after
# uv venv --python 3.12 && source .venv/bin/activate
# pip install docling vllm
vlm_options.engine = "vllm"

Defensive patterns

Strategy: validation

Validate before calling

import sys, importlib.util

if vlm_options.engine == 'vllm':
    if sys.version_info >= (3, 14):
        raise RuntimeError('vllm does not support Python 3.14 yet; run on <=3.13 or choose another engine')
    if importlib.util.find_spec('vllm') is None:
        raise ImportError('install vllm first')

Try / catch

try:
    model = VllmVlmModel(...)
except ImportError as e:
    if 'Python 3.14' in str(e):
        raise SystemExit('Switch to Python 3.13 or use the Transformers/MLX engine')
    raise

Prevention

Pin your project's Python version (3.10–3.13) when using GPU/vllm stacks
Check vLLM release notes for interpreter support before upgrading Python
Keep an engine-agnostic config so you can fall back to Transformers

When it happens

Trigger: Importing/constructing the vLLM VLM model on a Python >= 3.14 interpreter where the vllm import fails, which is guaranteed since no 3.14 wheels exist.

Common situations: New machines shipping 3.14 as default python; pyenv/uv setups that pick the newest interpreter; CI matrices upgraded to latest CPython.

Related errors

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