docling-project/docling · error · ImportError

qwen-vl-utils is required for NuExtract extraction. Please i

Error message

qwen-vl-utils is required for NuExtract extraction. Please install it with: pip install qwen-vl-utils

What it means

ImportError raised by build_nuextract_inputs in prompt_utils: constructing NuExtract-style vision inputs requires the optional qwen-vl-utils package (process_vision_info), and it is not installed. The message tells you exactly how to install it.

Source

Thrown at docling/models/extraction/prompt_utils.py:26

from PIL.Image import Image


def build_nuextract_inputs(
    processor: Any,
    images: list[Image],
    templates: list[str],
    device: str,
    extra_processor_kwargs: dict[str, Any],
) -> dict[str, Any]:
    """Build inputs using the NuExtract-specific template format.

    Requires qwen-vl-utils for vision processing.
    """
    try:
        from qwen_vl_utils import process_vision_info
    except ImportError:
        raise ImportError(
            "qwen-vl-utils is required for NuExtract extraction. "
            "Please install it with: pip install qwen-vl-utils"
        )

    inputs = []
    for pil_img, template in zip(images, templates):
        inputs.append(
            {
                "document": {"type": "image", "image": pil_img},
                "template": template,
            }
        )

    messages = [[{"role": "user", "content": [x["document"]]}] for x in inputs]

    texts = [
        processor.tokenizer.apply_chat_template(
            messages[i],

View on GitHub (pinned to 61d76f1ff3)

Solutions

pip install qwen-vl-utils and add it to the deployment's dependency list.
Add an environment check in deployment scripts: ensure 'import qwen_vl_utils' succeeds before starting extraction workers.
If you cannot install it, use an extraction path that does not require NuExtract vision input building.

Example fix

# before
# requirements.txt: docling-slim only
inputs = build_nuextract_inputs(...)  # ImportError

# after
# pip install qwen-vl-utils  (add to requirements.txt)
inputs = build_nuextract_inputs(...)  # ok

Defensive patterns

Strategy: validation

Validate before calling

try:
    import qwen_vl_utils  # noqa: F401
except ImportError:
    raise SystemExit('pip install qwen-vl-utils before running NuExtract extraction')

Try / catch

try:
    inputs = build_nuextract_inputs(images, templates, device, kwargs)
except ImportError as e:
    if 'qwen-vl-utils' in str(e):
        raise SystemExit('install qwen-vl-utils to use the NuExtract input builder')
    raise

Prevention

Include qwen-vl-utils in lockfiles for any image-based NuExtract flow.
Fail fast on missing optional deps at worker startup.

When it happens

Trigger: Invoking the NuExtract extraction path that uses prompt_utils.build_nuextract_inputs in an environment where 'from qwen_vl_utils import process_vision_info' raises ImportError.

Common situations: Slim installs (docling-slim) or hand-rolled requirements files that omit qwen-vl-utils; production Docker images built from a lockfile that predates the extraction feature.

Related errors

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