{"record":{"id":"5560aaeb6bf35b27","repo":"docling-project/docling","slug":"hugging-face-dataset-support-requires-huggingface","errorCode":null,"errorMessage":"Hugging Face dataset support requires 'huggingface_hub' to be installed.","messagePattern":"Hugging Face dataset support requires 'huggingface_hub' to be installed\\.","errorType":"console","errorClass":"SystemExit","httpStatus":null,"severity":"error","filePath":"perfs/iterate_pdf_pages.py","lineNumber":406,"sourceCode":"        logging.getLogger(logger_name).setLevel(logging.WARNING)\n\n    try:\n        yield\n    finally:\n        if not progress_bars_were_disabled:\n            enable_progress_bars()\n        for logger_name, level in previous_levels.items():\n            logging.getLogger(logger_name).setLevel(level)\n\n\ndef _resolve_input_dir(args: argparse.Namespace) -> Path:\n    if args.input_dir is not None:\n        return args.input_dir\n\n    try:\n        from huggingface_hub import snapshot_download\n    except ImportError as exc:\n        raise SystemExit(\n            \"Hugging Face dataset support requires 'huggingface_hub' to be installed.\"\n        ) from exc\n\n    assert args.repo_id is not None\n    with _suppress_huggingface_output():\n        snapshot_dir = Path(\n            snapshot_download(\n                repo_id=args.repo_id,\n                repo_type=\"dataset\",\n                revision=args.revision,\n                allow_patterns=\"pdf/**\",\n            )\n        )\n    pdf_dir = snapshot_dir / \"pdf\"\n    if not pdf_dir.is_dir():\n        raise SystemExit(\n            f\"Dataset '{args.repo_id}' does not contain a 'pdf/' subfolder.\"\n        )","sourceCodeStart":388,"sourceCodeEnd":424,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/perfs/iterate_pdf_pages.py#L388-L424","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\n$ uv run python perfs/iterate_pdf_pages.py --repo-id my-org/pdf-corpus\n# SystemExit: Hugging Face dataset support requires 'huggingface_hub' ...\n\n# after\n$ uv pip install huggingface_hub\n$ uv run python perfs/iterate_pdf_pages.py --repo-id my-org/pdf-corpus","handlingStrategy":"try-catch","validationCode":"try:\n    import huggingface_hub  # noqa: F401\nexcept ImportError:\n    raise SystemExit(\"Install huggingface_hub to use --repo-id mode\")","typeGuard":null,"tryCatchPattern":"try:\n    from huggingface_hub import snapshot_download\nexcept ImportError:\n    snapshot_download = None\n\nif snapshot_download is None:\n    # fall back to local dir mode or fail with install hint","preventionTips":["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."],"tags":["perf-tooling","huggingface","dependency","cli"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}