{"record":{"id":"f4f179a031f6b1e5","repo":"docling-project/docling","slug":"vllm-is-not-installed-it-is-not-yet-available-on-f4f179","errorCode":null,"errorMessage":"vllm is not installed. It is not yet available on Python 3.14.","messagePattern":"vllm is not installed\\. It is not yet available on Python 3\\.14\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"docling/models/vlm_pipeline_models/vllm_model.py","lineNumber":118,"sourceCode":"        self.processor = None  # used for CHAT templating in formulate_prompt()\n        self.device = \"cpu\"\n        self.max_new_tokens = vlm_options.max_new_tokens\n        self.temperature = vlm_options.temperature\n\n        if not self.enabled:\n            return\n\n        from transformers import AutoProcessor\n\n        try:\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                )\n            else:\n                raise ImportError(\n                    \"vllm is not installed. It is not yet available on Python 3.14.\"\n                )\n\n        # Device selection\n        self.device = decide_device(\n            accelerator_options.device, supported_devices=vlm_options.supported_devices\n        )\n        _log.debug(f\"Available device for VLM: {self.device}\")\n\n        # Resolve artifacts path / cache folder\n        repo_cache_folder = vlm_options.repo_id.replace(\"/\", \"--\")\n        if artifacts_path is None:\n            artifacts_path = self.download_models(\n                self.vlm_options.repo_id, revision=self.vlm_options.revision\n            )\n        elif (artifacts_path / repo_cache_folder).exists():\n            artifacts_path = artifacts_path / repo_cache_folder\n        else:","sourceCodeStart":100,"sourceCodeEnd":136,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/vlm_pipeline_models/vllm_model.py#L100-L136","documentation":"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.","triggerScenarios":"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.","commonSituations":"New machines shipping 3.14 as default python; pyenv/uv setups that pick the newest interpreter; CI matrices upgraded to latest CPython.","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"],"exampleFix":"# before: system python is 3.14\nvlm_options.engine = \"vllm\"  # ImportError: not available on 3.14\n# after\n# uv venv --python 3.12 && source .venv/bin/activate\n# pip install docling vllm\nvlm_options.engine = \"vllm\"","handlingStrategy":"validation","validationCode":"import sys, importlib.util\n\nif vlm_options.engine == 'vllm':\n    if sys.version_info >= (3, 14):\n        raise RuntimeError('vllm does not support Python 3.14 yet; run on <=3.13 or choose another engine')\n    if importlib.util.find_spec('vllm') is None:\n        raise ImportError('install vllm first')","typeGuard":null,"tryCatchPattern":"try:\n    model = VllmVlmModel(...)\nexcept ImportError as e:\n    if 'Python 3.14' in str(e):\n        raise SystemExit('Switch to Python 3.13 or use the Transformers/MLX engine')\n    raise","preventionTips":["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"],"tags":["vllm","python-version","environment","import-error"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}