sickn33/agentic-awesome-skills/huggingface-spaces

Hugging Face Spaces

When to Use

Use this skill when you need build, deploy, and maintain applications on Hugging Face Spaces — Gradio / Docker / Static SDKs, ZeroGPU and dedicated hardware, model loading, debugging, buckets, inference providers, community grants. Use whenever the user asks to create or host an app on Hugging Face, port existing code to a Space, diagnose build/runtime errors, or choose storage and inference hardware.

Hugging Face Spaces host machine-learning applications. Each Space has a git repository; live catalog totals change. This skill covers creating, building, debugging, and maintaining them.

Modified 2026-10-23: corrected eligibility/version assumptions, deployment/testing boundaries, storage/privacy and dependency recipes. Apache-2.0 upstream attribution is retained.

0. Getting ready

Before anything else:

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 authenticate locally with hf auth login; never paste the token into chat or logs — 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.

The hf-cli skill teaches an agent every hf command and is the recommended companion to this one. Install it with hf skills add hf-cli (add --claude --global to install for Claude Code as well, user-level).

1. What a Space is

A Space is a git repo with three possible SDKs:

• 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

Free, no creator cost: `cpu-basic` and `zero-a10g` (ZeroGPU). Static Spaces are also free and don't need hardware.

`cpu-basic` — 2 vCPU / 16 GB. For data viz, API-proxy Spaces, small CPU-bound models.

ZeroGPU (`zero-a10g`) — dynamic, per-request GPU allocation on NVIDIA RTX PRO 6000 Blackwell (sm_120). Two sizes: large (half MIG, 48 GB, 1× quota) and xlarge (full, 96 GB, 2× quota). Free for the Space creator; Space visitors consume their own daily quota (~5 min free / 40 min Pro / 60 min Enterprise). Gradio-only, PyTorch-first. Hosting eligibility depends on account age/standing and plan; check current ZeroGPU hosting limits before choosing hardware.

Dedicated GPU (T4, L4, A10G, L40S, A100, H200) — billed to the Space creator by the hour. List + pricing: hf spaces hardware. Only the creator can attach these, and only if canPay=True. Use when ZeroGPU genuinely doesn't fit — non-PyTorch main model with heavy init, very-large-model long-context inference, etc.

If a non-PRO user has a use case that wants ZeroGPU, you first check whether their account qualifies for free ZeroGPU hosting. If it does not, prepare a CPU-safe skeleton and discuss a grant request. See `references/grants.md`.

For the authoritative reference: https://huggingface.co/docs/hub/spaces-overview

2. Look for an existing demo first

Before deciding how to build anything, search for prior art:

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

If someone has built a similar Space, read its app.py and requirements.txt — that gives you the working pattern. Saves a lot of blind iteration. Mention to the user what you found before committing to an approach.

3. Decide SDK and hardware

Follow the user's explicit request first. If they were vague:

• 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`). Otherwise: read the README + inference code, prefer the PyTorch path, estimate VRAM (bf16 ≈ params_B × 2 GB; 48 GB holds at most 24B bf16 parameters in theory, with no room left for activations, KV cache or runtime overhead, or much larger with quantization — see `references/zerogpu.md` 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.

If the model genuinely won't fit, check Inference Providers as an alternative: see `references/inference-providers.md`. This avoids hosting the model at all.

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

The Space now exists at https://huggingface.co/spaces/<namespace>/<name> but is empty.

README.md frontmatter

Always required:

---
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: <reviewed-gradio-version>  # replace with a tested compatible release
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
---

\* Reasons to use an older Gradio: a custom component pins it, or you're adapting an existing demo and don't want to rewrite for 5.x→6.x breaking changes. Check the current supported/security status before retaining an older release; do not assume a historical pin remains suitable.

All frontmatter options: https://huggingface.co/docs/hub/spaces-config-reference

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):
    return pipe(prompt).images[0]
gr.Interface(fn=generate, inputs=gr.Text(), outputs=gr.Image()).launch()

Three rules — full treatment in `references/zerogpu.md`:

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.

requirements.txt

Short version:

• 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, …).
• Consult the current supported PyTorch list in the ZeroGPU docs; the four-version list in earlier snapshots is incomplete. 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`.

Per-SDK depth

• Gradio patterns (themes, gr.Examples, streaming, custom HTML components, gr.Server): `references/gradio.md`.
• 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` — read this whenever the Space targets ZeroGPU.

6. Iterate on the Space, not locally

Build a release candidate from the user request and deploy within the agreed visibility and cost scope — then use the live URL as your test loop. Run useful local parsing, unit and input-validation checks first. Then test an authorized private/staging Space: local success cannot establish ZeroGPU/runtime compatibility, and publication is a separate effect.

Once pushed, pick the cheapest update mechanism for each change — hot-reload for pure Python edits, hf upload for code-only files hot-reload can't touch, full rebuild only when requirements.txt / Dockerfile / README frontmatter actually changed. Full ladder + footguns (hot-reload poisoning factory reboot, runtime.sha lag, etc.) in `references/debugging.md`.

7. Verify

Don't trust RUNNING alone — the app can be running but broken. Four steps, in order:

A. Alive? Stage + hardware:

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