Hugging Face Spaces

0. Getting ready

1. Check the hf CLI is installed: which hf. If not, pip install -U huggingface_hub.
2. Check the user is logged in: hf auth whoami. If not, ask them to run ! hf auth login in this session — they'll need a write-scoped token from https://huggingface.co/settings/tokens.
3. Note whoami's canPay and isPro flags — they gate hardware choices below.

1. What a Space is

• Gradio — most Spaces. Python, fast iteration, supports ZeroGPU.
• Docker — arbitrary container. Use when you need a non-Python stack or a pre-built template (Streamlit, Argilla, Shiny, etc. — full list at https://huggingface.co/docs/hub/spaces-sdks-docker)..) Does not support ZeroGPU.
• Static — plain HTML, or a React/Svelte/Vue project built at deploy time. Use for in-browser ML (transformers.js / WebGPU / WebAssembly / onnxruntime-web), project pages, interactive reports, or Spaces that orchestrate other Spaces. No hardware needed.

Hardware tiers

2. Look for an existing demo first

hf spaces search "<model name or task>" --sdk gradio --limit 10

3. Decide SDK and hardware

• Default for a public ML demo: Gradio + ZeroGPU. Use this unless something below applies.
• The model's only inference path is non-PyTorch (ONNX / TF / JAX / vLLM as the MAIN model, with heavy init): dedicated GPU.
  • But: marginal non-torch tools (a small ONNX preprocessor, a TF utility) inside a torch-main pipeline are fine on ZeroGPU. The hijack only patches torch; init the non-torch lib inside @spaces.GPU and pay the short per-call init cost.
• Tiny / CPU-bound model, or API-proxy Space: cpu-basic (hardware-free isn't applicable to Gradio).
• Browser-side ML or project page: Static.
• Container with non-Python stack: Docker.

Sourcing the model

• GitHub repo — clone locally to read structure. If it already has a Gradio demo, the minimal viable path is to adapt it onto ZeroGPU (see references/zerogpu.md [blocked]). Otherwise: read the README + inference code, prefer the PyTorch path, estimate VRAM (bf16 ≈ params_B × 2 GB; 48 GB fits ≤24B params at bf16, or much larger with quantization — see references/zerogpu.md [blocked] for quantization on ZeroGPU).
• HF model repo — read its README, follow any linked GitHub.
• Paper / blog post — look for an official or unofficial implementation. Don't reimplement unless trivial or the user explicitly asks.
• Vague request — search Spaces first; surface results.

4. Create the Space

hf repos create <namespace>/<name> --type space --space-sdk <gradio|docker|static> \
    [--flavor zero-a10g|cpu-basic|<paid-flavor>] \
    [--secrets KEY=val] [--env KEY=val] \
    --public|--private|--protected \
    --exist-ok

• --space-sdk is required.
• --flavor selects hardware. zero-a10g is the (legacy) identifier for ZeroGPU. Omit for cpu-basic. Run hf spaces hardware for the full paid list and pricing.
• Visibility: --public (anyone can view), --private (only you), --protected (app is reachable but git repo / Files tab is private).
• --secrets KEY=val becomes an environment variable inside the Space and is not visible to visitors. Use for API keys, gated-repo tokens (HF_TOKEN=hf_…), etc. Can also be set later via hf spaces secrets set <id> KEY=val.
• --env KEY=val is visible to visitors — use only for non-sensitive config (GRADIO_SSR_MODE=false, PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True, etc.).

Note: hardware: in the README YAML is silently ignored — hardware is only set via --flavor at creation, or later via hf spaces settings <id> --hardware <name>.

5. Build the app

README.md frontmatter

---
title: ...
emoji: 🚀                # pick something representative
colorFrom: blue          # red|yellow|green|blue|indigo|purple|pink|gray (only these)
colorTo: indigo
sdk: gradio              # gradio | docker | static
sdk_version: 6.15.1      # latest stable unless you have a reason*
app_file: app.py         # gradio only (docker / static use Dockerfile / index.html)
short_description: ...   # ≤ 60 chars (server rejects longer)
python_version: "3.12"   # ZeroGPU officially supports 3.10.13 and 3.12.12
startup_duration_timeout: 30m   # default; bump to 1h for big LLMs / heavy downloads
---

Minimal ZeroGPU Gradio app

import spaces           # MUST come before torch / diffusers / transformers
import torch
import gradio as gr
from diffusers import DiffusionPipeline

pipe = DiffusionPipeline.from_pretrained("<repo>", torch_dtype=torch.bfloat16).to("cuda")

@spaces.GPU(duration=60)
def generate(prompt: str):
    """Generate an image from a text prompt."""   # docstring → API / MCP tool description
    return pipe(prompt).images[0]

gr.Interface(fn=generate, inputs=gr.Text(), outputs=gr.Image()).launch(mcp_server=True)

1. import spaces before torch / any CUDA-touching import. It monkey-patches torch.cuda.*; once CUDA is initialized in the main process, it's too late.
2. Load the model at module scope, .to("cuda") eagerly. ZeroGPU intercepts the call, packs weights to disk, and streams them into VRAM on the first @spaces.GPU entry. Lazy loading inside the decorator costs every user.
3. Decorate the function Gradio binds. Estimate duration to the realistic worst case (smaller = higher queue priority and tighter quota check). For input-dependent runtime, pass a callable.

Examples, docstrings, and MCP

• Add gr.Examples whenever it makes sense (the app takes input and representative inputs exist) — prefer the model/repo's own official examples. Keep example rows to the few inputs a user actually varies (prompt, image) and give the handler defaults for the rest (steps, seed, guidance) so a row is ["a prompt"], not a wall of knobs. Use cache_examples=True, cache_mode="lazy". See references/gradio.md [blocked].
• Give every API-triggered function a docstring and type hints. Each Gradio event handler is exposed over the API; the docstring + signature are what a caller — and the MCP tool schema — sees.
• Launch with demo.launch(mcp_server=True) (Gradio 5+) so the Space doubles as an MCP server: each API function becomes an MCP tool described by its docstring and hints.

requirements.txt

• Do NOT list: gradio, spaces, huggingface_hub (preinstalled and platform-managed; pinning them causes resolution failures or silently breaks the ZeroGPU runtime).
• Do list if you use them: torchvision, torchaudio (not preinstalled), plus everything else (diffusers, transformers, accelerate, sentencepiece, …).
• ZeroGPU only accepts torch 2.8.0, 2.9.1, 2.10.0, 2.11.0. Default to leaving torch unpinned (the runtime preinstalls the latest). Only pin when a dep forces it.
• For prebuilt CUDA-extension wheels (flash_attn, xformers, pytorch3d, nvdiffrast, diff_gaussian_rasterization, torchmcubes): use the prebuilt Blackwell wheels at https://huggingface.co/datasets/multimodalart/zerogpu-blackwell-wheels/tree/main/wheels. Full mapping + caveats in references/requirements.md [blocked].

Per-SDK depth

• Gradio patterns (themes, gr.Examples, streaming, custom HTML components, gr.Server): references/gradio.md [blocked].
• Docker: https://huggingface.co/docs/hub/spaces-sdks-docker. Examples: hf spaces list --filter docker.
• Static: https://huggingface.co/docs/hub/spaces-sdks-static. For built SPAs, set app_build_command: npm run build and app_file: dist/index.html in frontmatter.
• ZeroGPU specifics (decorator semantics, sizing, AoTI, generators, concurrency, pickle / gr.State across the worker boundary): references/zerogpu.md [blocked] — read this whenever the Space targets ZeroGPU.

6. Iterate on the Space, not locally

7. Verify

hf spaces info <ns>/<name> --expand runtime

hf spaces logs <ns>/<name> --tail 200

from gradio_client import Client, handle_file
import os
c = Client("<ns>/<name>", token=os.environ["HF_TOKEN"], httpx_kwargs={"timeout": 600})
print(c.view_api())                    # discover endpoints — don't guess
result = c.predict(..., api_name="/generate")

head = open(result, "rb").read(16)
# glTF / \x89PNG / RIFF…WEBP / RIFF…WAVE / [4:8]==b"ftyp" → png/jpg/webp/wav/mp4

8. Permanent storage (buckets)

hf buckets create <ns>/<bucket-name>                                          # --private optional
hf spaces volumes set <ns>/<space> -v hf://buckets/<ns>/<bucket-name>:/data   # read-write at /data

9. When things break

1. Read the logs: hf spaces logs <id> --build --follow (build error) or hf spaces logs <id> --follow (runtime error). Find the first error, not the last.
2. Grep references/known-errors.md [blocked] for the error string. Check if this is a known issue before trying your own fix — most common ZeroGPU / Gradio / dependency errors have a 1–2 line fix there.
3. Iterate using the cheapest rung from references/debugging.md [blocked]. The vast majority of issues resolve with log-reading + smoke-test loops; interactive dev mode + SSH is a heavy-hammer last resort.

Reference index