docling-project/docling · error · SystemExit

Hugging Face dataset support requires 'huggingface_hub' to b

Error message

Hugging Face dataset support requires 'huggingface_hub' to be installed.

What it means

SystemExit raised by _resolve_input_dir() in perfs/iterate_pdf_pages.py when the script is asked to pull its PDF corpus from a Hugging Face dataset (--repo-id given, no --input-dir) but the optional huggingface_hub package is not installed in the environment. The import is deferred so the dependency is only required when HF dataset mode is actually used.

Source

Thrown at perfs/iterate_pdf_pages.py:406

        logging.getLogger(logger_name).setLevel(logging.WARNING)

    try:
        yield
    finally:
        if not progress_bars_were_disabled:
            enable_progress_bars()
        for logger_name, level in previous_levels.items():
            logging.getLogger(logger_name).setLevel(level)


def _resolve_input_dir(args: argparse.Namespace) -> Path:
    if args.input_dir is not None:
        return args.input_dir

    try:
        from huggingface_hub import snapshot_download
    except ImportError as exc:
        raise SystemExit(
            "Hugging Face dataset support requires 'huggingface_hub' to be installed."
        ) from exc

    assert args.repo_id is not None
    with _suppress_huggingface_output():
        snapshot_dir = Path(
            snapshot_download(
                repo_id=args.repo_id,
                repo_type="dataset",
                revision=args.revision,
                allow_patterns="pdf/**",
            )
        )
    pdf_dir = snapshot_dir / "pdf"
    if not pdf_dir.is_dir():
        raise SystemExit(
            f"Dataset '{args.repo_id}' does not contain a 'pdf/' subfolder."
        )

View on GitHub (pinned to 61d76f1ff3)

Solutions

Install the package: 'pip install huggingface_hub' (or 'uv pip install huggingface_hub' / add it to the perf requirements).
Alternatively skip HF mode entirely by passing --input-dir /path/to/pdfs so no download dependency is needed.
Preinstall it as part of the benchmark environment setup script so the failure never reaches runtime.

Example fix

# before
$ uv run python perfs/iterate_pdf_pages.py --repo-id my-org/pdf-corpus
# SystemExit: Hugging Face dataset support requires 'huggingface_hub' ...

# after
$ uv pip install huggingface_hub
$ uv run python perfs/iterate_pdf_pages.py --repo-id my-org/pdf-corpus

Defensive patterns

Strategy: try-catch

Validate before calling

try:
    import huggingface_hub  # noqa: F401
except ImportError:
    raise SystemExit("Install huggingface_hub to use --repo-id mode")

Try / catch

try:
    from huggingface_hub import snapshot_download
except ImportError:
    snapshot_download = None

if snapshot_download is None:
    # fall back to local dir mode or fail with install hint

Prevention

Add huggingface_hub to the perf environment's requirements before first run.
Prefer --input-dir mode in CI to avoid the network dependency entirely.
Smoke-test the import at job startup rather than mid-benchmark.

When it happens

Trigger: Running 'python perfs/iterate_pdf_pages.py --repo-id <dataset>' in an environment lacking huggingface_hub (it is not part of Docling's core dependencies). The error chains the original ImportError as its cause.

Common situations: Fresh perf-benchmark environments provisioned only with docling's runtime deps; running the perf script inside the docling-slim install; CI caching that drops optional extras after dependency changes.

Related errors

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