docling-project/docling · error · ImportError

qwen-vl-utils is required for NuExtractTransformersModel. Pl

Error message

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

What it means

ImportError raised by the image-collection helper in NuExtractTransformersModel: processing vision inputs for the NuExtract model needs the optional qwen-vl-utils package, which is not installed in the current environment.

Source

Thrown at docling/models/extraction/nuextract_transformers_model.py:44

# Source code from https://huggingface.co/numind/NuExtract-2.0-8B
def process_all_vision_info(messages, examples=None):
    """
    Process vision information from both messages and in-context examples, supporting batch processing.

    Args:
        messages: List of message dictionaries (single input) OR list of message lists (batch input)
        examples: Optional list of example dictionaries (single input) OR list of example lists (batch)

    Returns:
        A flat list of all images in the correct order:
        - For single input: example images followed by message images
        - For batch input: interleaved as (item1 examples, item1 input, item2 examples, item2 input, etc.)
        - Returns None if no images were found
    """
    try:
        from qwen_vl_utils import fetch_image, process_vision_info
    except ImportError:
        raise ImportError(
            "qwen-vl-utils is required for NuExtractTransformersModel. "
            "Please install it with: pip install qwen-vl-utils"
        )

    from qwen_vl_utils import fetch_image, process_vision_info

    # Helper function to extract images from examples
    def extract_example_images(example_item):
        if not example_item:
            return []

        # Handle both list of examples and single example
        examples_to_process = (
            example_item if isinstance(example_item, list) else [example_item]
        )
        images = []

        for example in examples_to_process:

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Install the missing package: pip install qwen-vl-utils (or add it to your requirements/pyproject).
2. Install the Docling extra that bundles extraction dependencies if one is provided (e.g. docling[vlm]-style extras).
3. Verify with 'python -c "import qwen_vl_utils"' before launching a batch job.

Example fix

# before
# pip install docling-slim  (no qwen-vl-utils)
model = NuExtractTransformersModel(...)
model(...)  # ImportError

# after
# pip install qwen-vl-utils
model = NuExtractTransformersModel(...)
model(...)  # ok

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

try:
    result = model(inputs)
except ImportError as e:
    if 'qwen-vl-utils' in str(e):
        raise SystemExit('install qwen-vl-utils and restart the worker')
    raise

When it happens

Trigger: Running NuExtract extraction with the transformers backend (NuExtractTransformersModel) in an environment where 'import qwen_vl_utils' fails; the helper catches ImportError and re-raises with install instructions.

Common situations: Installing docling-slim or a minimal requirements set without the extraction extras; fresh venv/CI image that only lists core dependencies.

Related errors

• qwen-vl-utils is required for NuExtract extraction. Please i
• Examples batch length must match messages batch length
• Unsupported numpy array shape: {img.shape}
• Number of templates ({len(prompt)}) must match number of ima
• mlx-vlm is not installed. Please install it via `pip install

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