A Space is a git repo that rebuilds and restarts on every push. For Gradio you need three files — app.py, requirements.txt, and a README.md with Space metadata — then one push.
1. Write app.py
import gradio as gr
def greet(name):
return "Hello " + name + "!"
demo = gr.Interface(fn=greet, inputs="textbox", outputs="textbox")
demo.launch()
gr.Interface wraps your function in a UI; demo.launch() serves it on port 7860, which Spaces expects. Gradio needs Python 3.10 or higher. For a custom layout use gr.Blocks, but demo.launch() stays the same. The current Gradio quickstart has the full API.
2. Add requirements.txt and README
gradio
Lists the pip packages the Space installs at build time; pin a version (gradio==6.30.0, the current release — use whatever is latest when you build) once it works. The README.md YAML header configures the Space:
---
title: My Demo
emoji: 🤗
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 6.30.0
app_file: app.py
pinned: false
---
sdk: gradio and app_file are the load-bearing keys; set sdk_version to the current Gradio release (check the Gradio changelog).
3. Create the Space
hf repos create my-demo --repo-type space --sdk gradio
Creates your-username/my-demo as a Gradio Space. The flag is --sdk (not --space-sdk), and the subcommand is repos. You can also use New Space in the web UI.
4. Push your files
hf upload your-username/my-demo . --repo-type space
Uploads the current folder to the Space root; each push triggers a rebuild. Prefer git? Clone the Space repo and git push — the Hub treats both the same.
5. Set secrets and hardware
Never hard-code keys. In the Space’s Settings add a secret, then read it at runtime:
import os
token = os.getenv("HF_TOKEN")
Hardware: the default CPU Basic has no hourly cost, but per the Spaces overview, creating a Gradio Space now requires a paid plan — free personal accounts in good standing may instead host up to 2 Gradio Spaces on ZeroGPU. Set GPU tiers in Settings only if your plan allows it.
6. Read the build logs
The Space page shows a Building then Running badge with a live log. Open it on every push — a red build almost always names the missing package or the traceback line.
If it fails:
- Build failed:
ModuleNotFoundError— the import is not inrequirements.txt. Add it and push again. - “Runtime error” after build —
app.pycrashed on launch. Check the container log; common causes are a wrongapp_filepath or a missing secret read withos.getenv. - Space shows “Sleeping” — on free hardware a Space sleeps when unused and wakes on the next visit. Upgrade to paid hardware for always-on.
Next: download models with the hf CLI · a minimal RAG app in Python · pick an AI model.