Hugging Face Spaces with Gradio

Hugging Face Spaces host small web apps for free, and Gradio is the fastest way to build one in Python. In a dozen lines you can wrap any model in a web page with inputs, outputs and a shareable URL.

A First Gradio Interface

import gradio as gr
from transformers import pipeline

clf = pipeline("text-classification",
               model="distilbert/distilbert-base-uncased-finetuned-sst-2-english")

def predict(text):
    r = clf(text)[0]
    return {r["label"]: r["score"]}

demo = gr.Interface(fn=predict, inputs=gr.Textbox(label="Review"),
                    outputs=gr.Label(), title="Sentiment Checker")
demo.launch()

* Running on local URL:  http://127.0.0.1:7860

gr.Interface connects a Python function to input and output components. Open the local URL in a browser to try it. demo.launch(share=True) creates a temporary public link.

A Chatbot UI

gr.ChatInterface builds a chat window. Your function receives the new message and the history, and returns the reply:

import gradio as gr
from transformers import pipeline

chat = pipeline("text-generation", model="Qwen/Qwen2.5-0.5B-Instruct")

def respond(message, history):
    msgs = history + [{"role": "user", "content": message}]
    out = chat(msgs, max_new_tokens=200)
    return out[0]["generated_text"][-1]["content"]

gr.ChatInterface(respond, type="messages").launch()

* Running on local URL:  http://127.0.0.1:7860

Deploying to a Space

• On huggingface.co, click New Space, choose the Gradio SDK and a name.
• Add app.py containing your demo (Spaces runs it automatically).
• Add requirements.txt listing packages, e.g. transformers, torch.
• Push with Git or upload files in the browser; the Space builds and starts.
• Your app is live at huggingface.co/spaces/<user>/<name>.

requirements.txt Example

transformers
torch
sentence-transformers

(Space build log) Successfully installed transformers torch sentence-transformers ...

Hardware, Secrets and Calling a Space

Free Spaces run on CPU and go to sleep when unused. You can upgrade to paid GPU hardware, and ZeroGPU Spaces share GPUs on demand for eligible accounts. Store API keys as Secrets in the Space settings and read them with os.environ, never hard-code them.

Every Gradio app also exposes an API. Use gradio_client to call it from Python:

from gradio_client import Client

client = Client("your-username/sentiment-checker")
print(client.predict("Loved it!", api_name="/predict"))

{'label': 'POSITIVE', 'confidences': [...]}   (sample output)

Frequently asked questions

Are Hugging Face Spaces free?

Yes, basic CPU Spaces are free and sleep when idle. Persistent GPUs and upgraded hardware are paid.

What is the difference between Gradio and Streamlit on Spaces?

Both build Python web apps. Gradio is focused on ML demos with ready-made input/output components and an automatic API; Streamlit is a general data-app framework. Spaces supports both, plus Docker.

How do I keep my API key secret in a Space?

Add it under Settings, Variables and secrets, then read it in code with os.environ["NAME"]. Secrets are not visible in the public files.