{"record":{"id":"b9d6267c104184ef","repo":"docling-project/docling","slug":"phi-4-only-works-with-transformers-4-52-0-but-you","errorCode":null,"errorMessage":"Phi 4 only works with transformers<4.52.0 but you have {transformers_version=}. Please downgrade by running: pip install -U 'transformers<4.52.0'","messagePattern":"Phi 4 only works with transformers<4\\.52\\.0 but you have (.+?)\\. Please downgrade by running: pip install -U 'transformers<4\\.52\\.0'","errorType":"exception","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"docling/models/inference_engines/vlm/transformers_engine.py","lineNumber":177,"sourceCode":"        revision: str = \"main\",\n        model_type: TransformersModelType = TransformersModelType.AUTOMODEL,\n    ) -> None:\n        \"\"\"Load model and processor for a specific repository.\n\n        Args:\n            repo_id: HuggingFace repository ID\n            revision: Model revision\n            model_type: Type of model architecture\n        \"\"\"\n        transformers_version = importlib.metadata.version(\"transformers\")\n        parsed_transformers_version = version.parse(transformers_version)\n\n        # Check for Phi-4 compatibility\n        if (\n            repo_id == \"microsoft/Phi-4-multimodal-instruct\"\n            and parsed_transformers_version >= version.parse(\"4.52.0\")\n        ):\n            raise NotImplementedError(\n                f\"Phi 4 only works with transformers<4.52.0 but you have {transformers_version=}. \"\n                f\"Please downgrade by running: pip install -U 'transformers<4.52.0'\"\n            )\n        is_dots_model = repo_id in _DOTS_REPO_IDS\n        if is_dots_model and parsed_transformers_version.major >= 5:\n            raise NotImplementedError(\n                f\"{repo_id} is supported by the Transformers engine only with \"\n                f\"transformers<5, but you have {transformers_version=}. \"\n                \"Use a transformers-v4 environment, or use the vLLM engine.\"\n            )\n        if repo_id in _DOTS_FLASH_ATTN_REQUIRED_REPO_IDS:\n            _ensure_dots_flash_attn_import()\n\n        # Download or locate model artifacts using shared utility\n        def download_wrapper(repo_id: str, revision: str) -> Path:\n            return self.download_models(repo_id, revision=revision)\n\n        artifacts_path = resolve_model_artifacts_path(","sourceCodeStart":159,"sourceCodeEnd":195,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/inference_engines/vlm/transformers_engine.py#L159-L195","documentation":"TransformersVlmEngine enforces a version guard for microsoft/Phi-4-multimodal-instruct: the model only works with transformers<4.52.0. During model resolution it compares the installed transformers version and raises NotImplementedError when it is 4.52.0 or newer, telling you the exact downgrade command.","triggerScenarios":"Selecting the Phi-4 multimodal model on the Transformers engine while importlib.metadata reports transformers >= 4.52.0 — typically after a fresh environment install or an unpinned transformers upgrade.","commonSituations":"Environment drift: 'pip install -U transformers' or a new venv resolving the latest transformers; dependency resolvers pulling newer transformers via another package.","solutions":["Downgrade: pip install -U 'transformers<4.52.0'","Pin transformers in your project (e.g. 'transformers<4.52.0' in pyproject/requirements) so it does not drift back","Alternatively switch to a different VLM model that supports current transformers, keeping Phi-4 for the pinned env"],"exampleFix":"# before (transformers 4.53.x installed)\nmodel_config = EngineModelConfig(repo_id='microsoft/Phi-4-multimodal-instruct')\n# TransformersVlmEngine(...) -> NotImplementedError\n\n# after\n# terminal: pip install -U 'transformers<4.52.0'\nmodel_config = EngineModelConfig(repo_id='microsoft/Phi-4-multimodal-instruct')","handlingStrategy":"validation","validationCode":"import importlib.metadata\nfrom packaging.version import Version\n\ntv = Version(importlib.metadata.version('transformers'))\nif repo_id == 'microsoft/Phi-4-multimodal-instruct' and tv >= Version('4.52.0'):\n    raise SystemExit(\n        f'Phi-4 needs transformers<4.52.0 (found {tv}); pip install -U \\'transformers<4.52.0\\''\n    )","typeGuard":null,"tryCatchPattern":"try:\n    engine.initialize()\nexcept NotImplementedError as e:\n    if 'Phi 4' in str(e):\n        raise SystemExit('Downgrade transformers: pip install -U \\'transformers<4.52.0\\'') from e\n    raise","preventionTips":["Pin transformers<4.52.0 in any environment that runs Phi-4 multimodal","Run a startup version check comparing installed transformers against model-specific constraints","Isolate Phi-4 workloads in a dedicated environment so the pin does not fight other models"],"tags":["vlm","transformers","version-conflict","phi-4","dependency"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}