opendatalab/MinerU · error · ImportError

Please install transformers to use the transformers backend.

Error message

Please install transformers to use the transformers backend.

What it means

Raised on the transformers branch of VLM model loading (vlm_analyze.py) when `from transformers import AutoProcessor, Qwen2VLForConditionalGeneration` fails with ImportError. The transformers backend requires the transformers package (new enough for Qwen2-VL) before it can call from_pretrained on the auto-downloaded model path.

Source

Thrown at mineru/backend/vlm/vlm_analyze.py:90

                http_timeout = kwargs.get("http_timeout", 600)  # for http-client backend only
                server_headers = kwargs.get("server_headers", None)  # for http-client backend only
                max_retries = kwargs.get("max_retries", 3)  # for http-client backend only
                retry_backoff_factor = kwargs.get("retry_backoff_factor", 0.5)  # for http-client backend only
                # 从kwargs中移除这些参数，避免传递给不相关的初始化函数
                for param in ["batch_size", "max_concurrency", "http_timeout", "server_headers", "max_retries", "retry_backoff_factor"]:
                    if param in kwargs:
                        del kwargs[param]
                if backend not in ["http-client"] and not model_path:
                    model_path = auto_download_and_get_model_root_path("/","vlm")
                if backend == "transformers":
                    try:
                        from transformers import (
                            AutoProcessor,
                            Qwen2VLForConditionalGeneration,
                        )
                        from transformers import __version__ as transformers_version
                    except ImportError:
                        raise ImportError("Please install transformers to use the transformers backend.")

                    if version.parse(transformers_version) >= version.parse("4.56.0"):
                        dtype_key = "dtype"
                    else:
                        dtype_key = "torch_dtype"
                    device = get_device()
                    model = Qwen2VLForConditionalGeneration.from_pretrained(
                        model_path,
                        device_map={"": device},
                        **{dtype_key: "auto"},  # type: ignore
                    )
                    processor = AutoProcessor.from_pretrained(
                        model_path,
                        use_fast=True,
                    )
                    if batch_size == 0:
                        batch_size = set_default_batch_size()
                elif backend == "mlx-engine":

View on GitHub (pinned to 4fe4bde114)

Solutions

1. pip install transformers (>= the version supporting Qwen2-VL, e.g. 4.37+; note the code adapts dtype kwarg for >=4.56).
2. If already installed, run python -c "from transformers import Qwen2VLForConditionalGeneration" to surface the real underlying error and fix that dep.
3. Consider a dedicated virtualenv/uv env for MinerU to avoid version conflicts.

Example fix

# before
run(backend="transformers", ...)  # ImportError

# after
pip install "transformers>=4.51"
run(backend="transformers", ...)

def transformers_backend_available() -> bool:
    try:
        from transformers import AutoProcessor, Qwen2VLForConditionalGeneration  # noqa
        return True
    except ImportError:
        return False

try:
    vlm_analyze(..., backend="transformers")
except ImportError as e:
    if "install transformers" in str(e):
        subprocess.check_call([sys.executable, "-m", "pip", "install", "transformers"])
        vlm_analyze(..., backend="transformers")  # retry once
    else:
        raise

When it happens

Trigger: backend='transformers' with transformers not installed, an old version lacking Qwen2VLForConditionalGeneration, or a dependency conflict (tokenizers/numpy ABI) making the import raise.

Common situations: Minimal install chosen to avoid heavy GPU deps; transformers pinned <4.x by another app in the same env; broken env after partial pip upgrades.

Related errors

• Please install vllm to use the vllm-async-engine backend.
• Please install vllm to use the vllm-engine backend.
• Please install vllm to use the vllm-async-engine backend.
• Please install lmdeploy to use the lmdeploy-engine backend.
• Unsupported lmdeploy backend: {lm_backend}

AI-assisted analysis of opendatalab/MinerU@4fe4bde114 (2026-08-14). Data as JSON: /api/errors/0941c41074b99a9b. Report an issue: GitHub.