docling-project/docling · error · NotImplementedError

Phi 4 only works with transformers<4.52.0 but you have {tran

Q: What causes "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'" in docling-project/docling?

Downgrade: pip install -U 'transformers<4.52.0'

Error message

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'

What it means

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.

Source

Thrown at docling/models/inference_engines/vlm/transformers_engine.py:177

        revision: str = "main",
        model_type: TransformersModelType = TransformersModelType.AUTOMODEL,
    ) -> None:
        """Load model and processor for a specific repository.

        Args:
            repo_id: HuggingFace repository ID
            revision: Model revision
            model_type: Type of model architecture
        """
        transformers_version = importlib.metadata.version("transformers")
        parsed_transformers_version = version.parse(transformers_version)

        # Check for Phi-4 compatibility
        if (
            repo_id == "microsoft/Phi-4-multimodal-instruct"
            and parsed_transformers_version >= version.parse("4.52.0")
        ):
            raise NotImplementedError(
                f"Phi 4 only works with transformers<4.52.0 but you have {transformers_version=}. "
                f"Please downgrade by running: pip install -U 'transformers<4.52.0'"
            )
        is_dots_model = repo_id in _DOTS_REPO_IDS
        if is_dots_model and parsed_transformers_version.major >= 5:
            raise NotImplementedError(
                f"{repo_id} is supported by the Transformers engine only with "
                f"transformers<5, but you have {transformers_version=}. "
                "Use a transformers-v4 environment, or use the vLLM engine."
            )
        if repo_id in _DOTS_FLASH_ATTN_REQUIRED_REPO_IDS:
            _ensure_dots_flash_attn_import()

        # Download or locate model artifacts using shared utility
        def download_wrapper(repo_id: str, revision: str) -> Path:
            return self.download_models(repo_id, revision=revision)

        artifacts_path = resolve_model_artifacts_path(

View on GitHub (pinned to 61d76f1ff3)

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

Example fix

# before (transformers 4.53.x installed)
model_config = EngineModelConfig(repo_id='microsoft/Phi-4-multimodal-instruct')
# TransformersVlmEngine(...) -> NotImplementedError

# after
# terminal: pip install -U 'transformers<4.52.0'
model_config = EngineModelConfig(repo_id='microsoft/Phi-4-multimodal-instruct')

Defensive patterns

Strategy: validation

Validate before calling

import importlib.metadata
from packaging.version import Version

tv = Version(importlib.metadata.version('transformers'))
if repo_id == 'microsoft/Phi-4-multimodal-instruct' and tv >= Version('4.52.0'):
    raise SystemExit(
        f'Phi-4 needs transformers<4.52.0 (found {tv}); pip install -U \'transformers<4.52.0\''
    )

Try / catch

try:
    engine.initialize()
except NotImplementedError as e:
    if 'Phi 4' in str(e):
        raise SystemExit('Downgrade transformers: pip install -U \'transformers<4.52.0\'') from e
    raise

Prevention

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

When it happens

Trigger: 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.

Common situations: Environment drift: 'pip install -U transformers' or a new venv resolving the latest transformers; dependency resolvers pulling newer transformers via another package.

Related errors

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