{"record":{"id":"9b9ce701070a9a59","repo":"sgl-project/sglang","slug":"huggingface-hub-is-required-to-download-real-esrga","errorCode":null,"errorMessage":"huggingface_hub is required to download Real-ESRGAN weights. Install it with: pip install huggingface_hub","messagePattern":"huggingface_hub is required to download Real-ESRGAN weights\\. Install it with: pip install huggingface_hub","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/postprocess/realesrgan_upscaler.py","lineNumber":740,"sourceCode":"        if not os.path.isfile(local_path):\n            tmp_path = f\"{local_path}.tmp\"\n            logger.info(\"Downloading Real-ESRGAN weights from URL %s\", model_path)\n            torch.hub.download_url_to_file(model_path, tmp_path, progress=False)\n            os.replace(tmp_path, local_path)\n        _RESOLVED_MODEL_PATH_CACHE[model_path] = local_path\n        return local_path\n\n    # Parse optional \"repo_id:filename\" syntax; fall back to default filename.\n    if \":\" in model_path and not model_path.startswith(\"/\"):\n        repo_id, filename = model_path.split(\":\", 1)\n    else:\n        repo_id = model_path\n        filename = _DEFAULT_REALESRGAN_FILENAME\n\n    try:\n        from huggingface_hub import hf_hub_download\n    except ImportError as e:\n        raise ImportError(\n            \"huggingface_hub is required to download Real-ESRGAN weights. \"\n            \"Install it with: pip install huggingface_hub\"\n        ) from e\n\n    logger.info(\n        \"Downloading Real-ESRGAN weights from HF repo %s (file: %s)\",\n        repo_id,\n        filename,\n    )\n    try:\n        local_path = hf_hub_download(\n            repo_id=repo_id,\n            filename=filename,\n        )\n    except Exception as e:\n        raise FileNotFoundError(\n            f\"Failed to download Real-ESRGAN weights from HuggingFace repo \"\n            f\"'{repo_id}' (file: '{filename}'). If you are using a custom \"","sourceCodeStart":722,"sourceCodeEnd":758,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/postprocess/realesrgan_upscaler.py#L722-L758","documentation":"ImportError raised by _resolve_model_path when the model_path is not a local file, so weights must be fetched from HuggingFace, but huggingface_hub is not installed in the environment.","triggerScenarios":"Constructing/using RealESRGANUpscaler with model_path='ai-forever/RealESRGAN_x4' (or default) in an environment where 'import huggingface_hub' fails.","commonSituations":"Minimal Docker images or slim sglang installs without the HF hub extra; running in an offline CI that stripped optional deps.","solutions":["pip install huggingface_hub","Or pre-download the .pth locally and pass its file path as model_path"],"exampleFix":"# before\nRealESRGANUpscaler(model_path=\"ai-forever/RealESRGAN_x4\")\n# after\npip install huggingface_hub  # or pass local path\nRealESRGANUpscaler(model_path=\"/models/RealESRGAN_x4.pth\")","handlingStrategy":"fallback","validationCode":"try:\n    import huggingface_hub  # noqa\nexcept ImportError:\n    assert os.path.isfile(model_path), \"need local .pth when huggingface_hub absent\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Install huggingface_hub in deployment images","Vendor checkpoints locally for offline environments"],"tags":["realesrgan","huggingface","dependency","postprocess"],"backgroundTag":"missing-optional-dependency","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}