sgl-project/sglang · error · ImportError

huggingface_hub is required to download Real-ESRGAN weights.

Error message

huggingface_hub is required to download Real-ESRGAN weights. Install it with: pip install huggingface_hub

What it means

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.

Source

Thrown at python/sglang/multimodal_gen/runtime/postprocess/realesrgan_upscaler.py:740

        if not os.path.isfile(local_path):
            tmp_path = f"{local_path}.tmp"
            logger.info("Downloading Real-ESRGAN weights from URL %s", model_path)
            torch.hub.download_url_to_file(model_path, tmp_path, progress=False)
            os.replace(tmp_path, local_path)
        _RESOLVED_MODEL_PATH_CACHE[model_path] = local_path
        return local_path

    # Parse optional "repo_id:filename" syntax; fall back to default filename.
    if ":" in model_path and not model_path.startswith("/"):
        repo_id, filename = model_path.split(":", 1)
    else:
        repo_id = model_path
        filename = _DEFAULT_REALESRGAN_FILENAME

    try:
        from huggingface_hub import hf_hub_download
    except ImportError as e:
        raise ImportError(
            "huggingface_hub is required to download Real-ESRGAN weights. "
            "Install it with: pip install huggingface_hub"
        ) from e

    logger.info(
        "Downloading Real-ESRGAN weights from HF repo %s (file: %s)",
        repo_id,
        filename,
    )
    try:
        local_path = hf_hub_download(
            repo_id=repo_id,
            filename=filename,
        )
    except Exception as e:
        raise FileNotFoundError(
            f"Failed to download Real-ESRGAN weights from HuggingFace repo "
            f"'{repo_id}' (file: '{filename}'). If you are using a custom "

View on GitHub (pinned to 0132848349)

Solutions

1. pip install huggingface_hub
2. Or pre-download the .pth locally and pass its file path as model_path

Example fix

# before
RealESRGANUpscaler(model_path="ai-forever/RealESRGAN_x4")
# after
pip install huggingface_hub  # or pass local path
RealESRGANUpscaler(model_path="/models/RealESRGAN_x4.pth")

try:
    import huggingface_hub  # noqa
except ImportError:
    assert os.path.isfile(model_path), "need local .pth when huggingface_hub absent"

When it happens

Trigger: Constructing/using RealESRGANUpscaler with model_path='ai-forever/RealESRGAN_x4' (or default) in an environment where 'import huggingface_hub' fails.

Common situations: Minimal Docker images or slim sglang installs without the HF hub extra; running in an offline CI that stripped optional deps.

Related errors

• Failed to download Real-ESRGAN weights from HuggingFace repo
• Unsupported activation type: {act_type}
• Unsupported RRDBNet conv_first input channels: {in_channels}
• All frames in a batch must have the same resolution
• Failed to load Real-ESRGAN checkpoint from '{resolved_path}'

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/9b9ce701070a9a59. Report an issue: GitHub.