docling-project/docling · error · ImportError

transformers >=4.46 is not installed. Please install Docling

Error message

transformers >=4.46 is not installed. Please install Docling with the required extras `pip install docling[vlm]`.

What it means

The VLM picture-description model needs torch and transformers>=4.46 (AutoModelForImageTextToText). If either import fails at init, Docling raises this ImportError directing you to install the [vlm] extras rather than exposing a bare ModuleNotFoundError.

Source

Thrown at docling/models/stages/picture_description/picture_description_vlm_model.py:63

        )
        self.options: PictureDescriptionVlmOptions

        if self.enabled:
            if artifacts_path is None:
                artifacts_path = self.download_models(repo_id=self.options.repo_id)
            else:
                artifacts_path = Path(artifacts_path) / self.options.repo_cache_folder

            self.device = decide_device(accelerator_options.device)

            try:
                import torch
                from transformers import (
                    AutoModelForImageTextToText,
                    AutoProcessor,
                )
            except ImportError:
                raise ImportError(
                    "transformers >=4.46 is not installed. Please install Docling with the required extras `pip install docling[vlm]`."
                )

            # Initialize processor and model
            with _model_init_lock:
                self.processor = AutoProcessor.from_pretrained(artifacts_path)
                tokenizer = getattr(self.processor, "tokenizer", None)
                if tokenizer is not None:
                    tokenizer.padding_side = self.options.padding_side
                self.model = AutoModelForImageTextToText.from_pretrained(
                    artifacts_path,
                    device_map=self.device,
                    dtype=torch.bfloat16,
                    _attn_implementation=(
                        "flash_attention_2"
                        if self.device.startswith("cuda")
                        and accelerator_options.cuda_use_flash_attention2
                        else "sdpa"

View on GitHub (pinned to 61d76f1ff3)

Solutions

Install the extras: pip install 'docling[vlm]' (or pip install 'transformers>=4.46' torch).
If another dependency pins transformers below 4.46, upgrade or relax that pin.
Verify: python -c "from transformers import AutoModelForImageTextToText".

Example fix

# before
# ImportError: transformers >=4.46 is not installed

# after
$ pip install "docling[vlm]"

Defensive patterns

Strategy: validation

Validate before calling

try:
    from transformers import AutoModelForImageTextToText  # requires >=4.46
    vlm_ok = True
except ImportError:
    vlm_ok = False

if use_vlm_descriptions and not vlm_ok:
    raise SystemExit("VLM picture description requires: pip install 'docling[vlm]'")

Try / catch

try:
    PictureDescriptionVlmModel(options=opts)
except ImportError as e:
    if "docling[vlm]" in str(e):
        log.warning("VLM extras missing; disabling picture descriptions")
        opts.enabled = False
    else:
        raise

Prevention

Pin transformers>=4.46 (or install docling[vlm]) in the deployment manifest.
Smoke-test the AutoModelForImageTextToText import in CI for VLM-enabled builds.
Check the extras before enabling VLM options so failures happen at deploy time, not run time.

When it happens

Trigger: Enabling picture description with the local VLM model in an environment lacking the vlm extras — docling-slim without extras, or a full install predating the extras split — so 'from transformers import AutoModelForImageTextToText' fails.

Common situations: Minimal/slim installs; older transformers (<4.46) pinned by another dependency so the symbol does not exist; CI images without the vlm extras.

Related errors

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