odysseus-dev/odysseus · error · HTTPException

huggingface_hub is required to download MLX image model snap

Error message

huggingface_hub is required to download MLX image model snapshots. Install the model requirements in the selected Python environment.

What it means

Raised by _snapshot_path in scripts/mlx_image_server.py when the model string is not an existing local path and the optional huggingface_hub package cannot be imported in the server's Python environment. The server needs snapshot_download to fetch MLX image model weights from the Hub; without the dependency it returns HTTP 503 instead of an ImportError traceback.

Source

Thrown at scripts/mlx_image_server.py:152

    )


def _resolve_bridge(names: list[str]) -> str:
    for name in names:
        found = _resolve_cli(name)
        if found:
            return found
    return ""


def _snapshot_path(model: str) -> Path:
    p = Path(model).expanduser()
    if p.exists():
        return p
    try:
        from huggingface_hub import snapshot_download
    except Exception as e:
        raise HTTPException(
            503,
            "huggingface_hub is required to download MLX image model snapshots. "
            "Install the model requirements in the selected Python environment.",
        ) from e
    return Path(snapshot_download(model))


def _weights_path(model: str) -> Path:
    p = Path(model).expanduser()
    if p.is_file():
        return p
    snap = _snapshot_path(model)
    if snap.is_file():
        return snap
    candidates = sorted(snap.rglob("*.safetensors"))
    if not candidates:
        raise HTTPException(500, f"No safetensors weights found for {model} in {snap}")
    return candidates[0]

View on GitHub (pinned to f9235ebbf1)

Solutions

1. Install huggingface_hub in the exact environment used to launch mlx_image_server.py (pip install -U huggingface_hub)
2. Verify with: <launch-python> -c 'import huggingface_hub' from the same interpreter
3. Alternatively pre-download the snapshot and pass a local absolute path as --model so snapshot_download is never needed

Example fix

# before
python scripts/mlx_image_server.py --model black-forest-labs/FLUX.1-schnell
# after
pip install -U huggingface_hub
python scripts/mlx_image_server.py --model black-forest-labs/FLUX.1-schnell

import importlib.util, sys, subprocess
spec = importlib.util.find_spec('huggingface_hub')
if spec is None:
    subprocess.check_call([sys.executable, '-m', 'pip', 'install', '-U', 'huggingface_hub'])

def has_hf_hub() -> bool:
    import importlib.util
    return importlib.util.find_spec('huggingface_hub') is not None

When it happens

Trigger: Requesting any MLX model by repo id (e.g. 'flux-1-schnell' or a HiDream/Boogu repo) when huggingface_hub is not installed in the Python that launched the server, and the model is not already a local directory.

Common situations: Server launched from a different virtualenv/conda env than the one where dependencies were installed; Apple Silicon MLX setup where only mflux was pip-installed; system python3 vs homebrew python mismatch; fresh checkout without running requirements install.

Related errors

• Pillow is required for MLX image edit bridge inputs.
• Pillow is required for MLX image edit bridge masks.
• Boogu MLX serving requires boogu-image-mlx in the launch Pyt
• {cli} not found in PATH or next to {sys.executable}. Install
• HTTP ${res.status} ${res.statusText}${msg ? `: ${msg}` : ''}

AI-assisted analysis of odysseus-dev/odysseus@f9235ebbf1 (2026-08-14). Data as JSON: /api/errors/48f6ee6aa56f693d. Report an issue: GitHub.