gradio-space-creator

name

gradio-space-creator

description

Create and deploy Gradio apps on HuggingFace Spaces. Covers full lifecycle: repo creation, ZeroGPU setup, custom theming/CSS, model loading, API integration, video generation, persistent storage with HF Buckets, and deployment. Use when asked to: build a Gradio app, create an HF Space, deploy a demo, make an interactive ML demo, build a Space with GPU, style a Gradio app, add persistent storage to a Space, mount a bucket, or any task involving Gradio + HuggingFace Spaces. Triggers on: "gradio", "hf space", "huggingface space", "build a space", "create a demo", "deploy on spaces", "zerogpu", "gradio app", "persistent storage", "mount bucket", "space storage".

Gradio Space Creator

Workflow

1. Plan: Determine if the space needs GPU (model inference) or CPU-only (API calls), and if it needs persistent storage
2. Create repo: hf repos create <user/space-name> --type space --space-sdk gradio [--flavor zero-a10g]
3. Write files: app.py, requirements.txt, README.md (with YAML frontmatter). Always include show_error=True in demo.launch() — without it, runtime errors are silent.
4. Set hardware: ZeroGPU for GPU, cpu-basic for API-only
5. Set secrets: HF_TOKEN and any other API keys
6. Mount storage (if needed): Create a bucket and mount as a volume for persistent read-write storage at /data. See references/setup.md
7. Push with LFS: Track binary files with git-lfs before pushing
8. Monitor: Tail the SSE log stream to see build/runtime output in real time (see references/setup.md). No sleep/polling needed.
9. Test: Verify end-to-end with uvx hf-gradio predict (quick) or gradio_client.Client.predict() (full). See references/setup.md.
10. Iterate: For gr.Blocks Spaces, use hf spaces hot-reload user/space-name -f app.py for app.py-only changes (no rebuild). For gr.Server Spaces, always use git push (hot-reload is incompatible). Use git push when requirements.txt or README.md change (triggers full rebuild).

Key References

• Space setup, pushing, logs, secrets, gated models, persistent storage: See references/setup.md
• ZeroGPU, model loading, @spaces.GPU, patching, InferenceClient, Server Mode: See references/zerogpu.md
• Theming, CSS, dark mode, fonts, mobile pitfalls: See references/styling.md
• Components, state, events, examples, video generation: See references/components.md

Critical Rules

1. max-width not width — fixed width breaks mobile
2. !important on all CSS — Gradio styles are aggressive
3. Load models at module level — not inside @spaces.GPU functions
4. Binary files need git-lfs — HF rejects untracked binaries
5. README colorFrom/colorTo must be one of: red, yellow, green, blue, indigo, purple, pink, gray.
6. Even dimensions for h264 — if w % 2: w -= 1
7. Check logs after every deploy — use the SSE logs endpoint
8. Always test via Gradio API — don't rely on logs alone; use uvx hf-gradio predict or gradio_client.Client.predict() to verify end-to-end
9. Set _dark variants for all theme properties in dark themes
10. Override --neutral-50/100/200 CSS vars to eliminate white in dark themes
11. Pin dependency versions in requirements.txt — except torch (HF build system manages it in a cached Docker layer; pinning a different version silently fails)
12. Check model's required transformers version — newer architectures (e.g. Qwen 3.5) need transformers 5.x+; if KeyError on model_type, upgrade or install from source
13. trust_remote_code=True for models with custom architectures — without it, transformers may call raw CUDA at module level, which ZeroGPU blocks
14. Gradio 6 SSR can hang with slow startup (large model loading) — use ssr_mode=False (or set GRADIO_SSR_MODE=false env var on HF). See references/setup.md
15. accelerate required for device_map="cuda" — always include it in requirements.txt
16. gr.Server needs GRADIO_SSR_MODE=false env var on HF — set via api.add_space_variable(). See references/setup.md
17. @spaces.GPU and @app.api on SEPARATE functions — never stack them. See references/zerogpu.md
18. import spaces must be the FIRST import — before torch, torchaudio, or any CUDA-dependent package. spaces monkey-patches CUDA hooks at import time; if anything loads CUDA first, you'll get libcudart.so.X: cannot open shared object file at startup (even with ZeroGPU)
19. Don't pin packages already pinned by your dependencies — if a library (e.g. ace_step) already pins transformers==4.50.0, don't also add transformers to requirements.txt. Pip conflicts will fail the build. Let the package's transitive deps win.

Minimal Template

import os
import gradio as gr

css = ".gradio-container { max-width: 900px !important; margin: 0 auto !important; }"

def process(input_data):
    return result

with gr.Blocks() as demo:
    gr.Markdown("# My App")
    inp = gr.Image(label="Input", type="pil")
    out = gr.Image(label="Output", type="pil")
    btn = gr.Button("Go!", variant="primary")
    btn.click(fn=process, inputs=[inp], outputs=[out])

demo.launch(css=css, show_error=True)

Gradio 6.0+ note: theme= and css= are now passed to demo.launch(), not gr.Blocks().

Server Mode (Custom Frontend)

For spaces with a fully custom HTML/JS frontend, use gr.Server instead of gr.Blocks. It inherits from FastAPI, supports @app.api() queue endpoints, MCP, and ZeroGPU. See references/zerogpu.md.