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, 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, 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".

Gradio Space Creator

Workflow

1. Plan: Determine if the space needs GPU (model inference) or CPU-only (API calls)
2. Create repo: hf repo create <name> --type space --space-sdk gradio
3. Write files: app.py, requirements.txt, README.md (with YAML frontmatter)
4. Set hardware: ZeroGPU for GPU, cpu-basic for API-only
5. Set secrets: HF_TOKEN and any other API keys
6. Push with LFS: Track binary files with git-lfs before pushing
7. Monitor: Check logs via HF API, poll build status
8. Test: Verify the space works end-to-end via the Gradio API (see references/setup.md)
9. Iterate with hot-reload: Use hf spaces hot-reload user/space-name -f app.py for fast iteration — no container restart needed. Commit to persist changes. Only use git push for dependency or README changes.

Key References

• Space setup, pushing, logs, secrets, gated models: See references/setup.md
• ZeroGPU, model loading, @spaces.GPU, patching, InferenceClient: 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 colorTo must be: 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; call 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
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

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(title="My App", css=css) 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()