opendatalab/MinerU · error · HybridDependencyError

`{backend}` requires local pipeline dependencies (`mineru[pi

Error message

`{backend}` requires local pipeline dependencies (`mineru[pipeline]`, including `torch`). Install `mineru[pipeline]` or `mineru[core]`. If you need a lightweight remote client without local `torch`, use `vlm-http-client` instead.

What it means

HybridDependencyError raised by ensure_backend_dependencies(): any backend starting with 'hybrid-' requires local pipeline dependencies (torch et al., the mineru[pipeline] extra). The check is a lightweight importlib.util.find_spec('torch') probe, so a missing torch install fails fast with an actionable install hint instead of a confusing deep ImportError.

Source

Thrown at mineru/cli/common.py:73

class HybridDependencyError(RuntimeError):
    pass


def build_hybrid_dependency_error_message(backend: str) -> str:
    return (
        f"`{backend}` requires local pipeline dependencies (`mineru[pipeline]`, "
        "including `torch`). Install `mineru[pipeline]` or `mineru[core]`. "
        "If you need a lightweight remote client without local `torch`, "
        "use `vlm-http-client` instead."
    )


def ensure_backend_dependencies(backend: str) -> None:
    if not backend.startswith("hybrid-"):
        return
    if importlib.util.find_spec("torch") is None:
        raise HybridDependencyError(build_hybrid_dependency_error_message(backend))


def _load_hybrid_analyze_entrypoint(entrypoint_name: str, backend: str):
    """加载统一 hybrid analyze 入口，解析强度由公开 effort 参数控制。"""
    ensure_backend_dependencies(backend)
    module_name = "mineru.backend.hybrid.hybrid_analyze"
    try:
        hybrid_analyze = importlib.import_module(module_name)
    except (ImportError, ModuleNotFoundError) as exc:
        raise HybridDependencyError(
            build_hybrid_dependency_error_message(backend)
        ) from exc
    return getattr(hybrid_analyze, entrypoint_name)


def utf8_byte_length(value: str) -> int:
    return len(value.encode("utf-8"))

View on GitHub (pinned to 4fe4bde114)

Solutions

1. pip install 'mineru[pipeline]' or 'mineru[core]' to pull torch and pipeline deps
2. If you intentionally run without torch, use vlm-http-client / hybrid-http-client against a remote server instead of a local hybrid-engine
3. Verify with python -c "import importlib.util; print(importlib.util.find_spec('torch'))"
4. In Docker, base the image on a variant that includes the pipeline extra

Example fix

# before
pip install mineru
mineru -p doc.pdf -b hybrid-engine  # HybridDependencyError

# after
pip install 'mineru[pipeline]'
mineru -p doc.pdf -b hybrid-engine

import importlib.util

if backend.startswith("hybrid-") and importlib.util.find_spec("torch") is None:
    raise SystemExit(
        f"{backend} needs torch locally. Install mineru[pipeline], or switch to "
        "hybrid-http-client for a remote, torch-free setup."
    )

def can_run_hybrid_locally() -> bool:
    import importlib.util
    return importlib.util.find_spec("torch") is not None

try:
    run_hybrid(...)
except HybridDependencyError:
    # either install mineru[pipeline] or transparently switch to the remote client
    run_hybrid_via_http_client(...)

When it happens

Trigger: Running hybrid-engine (or any 'hybrid-*' backend) in a slim install (pip install mineru without extras) where torch is absent; slim Docker images; CI environments that deliberately exclude torch to keep images small.

Common situations: Installing the lightweight client wheel for vlm-http-client usage and then switching to hybrid-engine; CI images trimmed of torch; venvs created for the API client only.

Related errors

• effort must be "medium" or "high"
• Unsupported hybrid effort: {effort}
• Invalid effort. Allowed values: {allowed_values}
• Invalid effort. Allowed values: {allowed_values}
• S3 reader/writer requires optional dependencies. Install the

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