Gradio Cheat Sheet

Overview

Gradio is a Python library for building interactive web-based demos for machine learning models. It automatically generates user interfaces from Python functions, supports a wide range of input/output components (text, images, audio, video, files, dataframes), and creates both a web UI and a REST API endpoint. Gradio apps can be shared via public links, embedded in web pages, or deployed to HuggingFace Spaces.

Gradio is the standard tool for sharing ML model demos in the research community and is deeply integrated with the HuggingFace ecosystem. It supports real-time streaming, queuing for heavy workloads, authentication, custom CSS themes, and event-driven interactivity.

Installation

pip install gradio

# Verify
python -c "import gradio as gr; print(gr.__version__)"

Core Usage

Simple Interface

import gradio as gr

def greet(name, intensity):
    return f"Hello, {name}!" + "!" * intensity

demo = gr.Interface(
    fn=greet,
    inputs=[
        gr.Textbox(label="Name"),
        gr.Slider(0, 10, value=1, label="Excitement")
    ],
    outputs=gr.Textbox(label="Greeting"),
    title="Greeting App",
    description="Enter your name for a personalized greeting."
)

demo.launch()
# Opens at http://localhost:7860

Input/Output Components

Component	Type	Usage
gr.Textbox	Text	Single/multi-line text
gr.Number	Numeric	Integer/float input
gr.Slider	Numeric	Range selection
gr.Checkbox	Boolean	True/false toggle
gr.Dropdown	Selection	Single/multi select
gr.Radio	Selection	Radio buttons
gr.Image	Media	Image upload/display
gr.Audio	Media	Audio upload/play
gr.Video	Media	Video upload/play
gr.File	File	File upload/download
gr.Dataframe	Table	Pandas dataframe
gr.JSON	Data	JSON display
gr.Code	Code	Syntax-highlighted code
gr.Markdown	Text	Rendered Markdown
gr.Plot	Chart	Matplotlib/Plotly plots
gr.Gallery	Media	Image gallery
gr.Chatbot	Chat	Chat message display

Image Classification Example

import gradio as gr
from transformers import pipeline

classifier = pipeline("image-classification", model="google/vit-base-patch16-224")

def classify(image):
    results = classifier(image)
    return {r["label"]: r["score"] for r in results}

demo = gr.Interface(
    fn=classify,
    inputs=gr.Image(type="pil"),
    outputs=gr.Label(num_top_classes=5),
    title="Image Classifier",
    examples=["cat.jpg", "dog.jpg"]
)

demo.launch()

Blocks API (Advanced Layout)

import gradio as gr

with gr.Blocks(theme=gr.themes.Soft()) as demo:
    gr.Markdown("# My Application")

    with gr.Row():
        with gr.Column(scale=2):
            input_text = gr.Textbox(label="Input", lines=5)
            model_choice = gr.Dropdown(
                ["gpt-4o", "claude-3", "llama-3"],
                label="Model",
                value="gpt-4o"
            )
            submit_btn = gr.Button("Submit", variant="primary")

        with gr.Column(scale=3):
            output_text = gr.Textbox(label="Output", lines=10)
            confidence = gr.Number(label="Confidence")

    with gr.Accordion("Advanced Settings", open=False):
        temperature = gr.Slider(0, 2, value=0.7, label="Temperature")
        max_tokens = gr.Slider(100, 4000, value=1000, label="Max Tokens")

    def process(text, model, temp, tokens):
        return f"Processed: {text} with {model}", 0.95

    submit_btn.click(
        fn=process,
        inputs=[input_text, model_choice, temperature, max_tokens],
        outputs=[output_text, confidence]
    )

demo.launch()

Chat Interface

import gradio as gr
from openai import OpenAI

client = OpenAI()

def chat(message, history):
    messages = [{"role": "system", "content": "You are a helpful assistant."}]
    for h in history:
        messages.append({"role": "user", "content": h[0]})
        if h[1]:
            messages.append({"role": "assistant", "content": h[1]})
    messages.append({"role": "user", "content": message})

    response = client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
        stream=True
    )

    partial = ""
    for chunk in response:
        if chunk.choices[0].delta.content:
            partial += chunk.choices[0].delta.content
            yield partial

demo = gr.ChatInterface(
    fn=chat,
    title="AI Chat",
    description="Chat with GPT-4o",
    examples=["Explain quantum computing", "Write a haiku"],
    retry_btn="Retry",
    undo_btn="Undo",
    clear_btn="Clear"
)

demo.launch()

State and Events

import gradio as gr

with gr.Blocks() as demo:
    # Session state
    counter = gr.State(0)

    display = gr.Number(label="Count", value=0)
    inc_btn = gr.Button("Increment")
    dec_btn = gr.Button("Decrement")

    def increment(count):
        return count + 1, count + 1

    def decrement(count):
        return count - 1, count - 1

    inc_btn.click(increment, inputs=counter, outputs=[counter, display])
    dec_btn.click(decrement, inputs=counter, outputs=[counter, display])

    # Event chaining
    text_input = gr.Textbox()
    word_count = gr.Number(label="Words")

    text_input.change(
        fn=lambda t: len(t.split()),
        inputs=text_input,
        outputs=word_count
    )

demo.launch()

Configuration

Launch Options

demo.launch(
    server_name="0.0.0.0",       # Listen on all interfaces
    server_port=7860,             # Port
    share=True,                   # Create public URL
    auth=("admin", "password"),   # Simple auth
    ssl_certfile="cert.pem",      # HTTPS
    ssl_keyfile="key.pem",
    show_error=True,              # Show tracebacks
    max_threads=40,               # Concurrent requests
)

# Multiple users auth
demo.launch(auth=[("user1", "pass1"), ("user2", "pass2")])

# Custom auth function
def auth_fn(username, password):
    return username == "admin" and password == "secret"

demo.launch(auth=auth_fn)

Queue for Heavy Workloads

demo = gr.Interface(fn=slow_function, inputs="text", outputs="text")
demo.queue(max_size=20, default_concurrency_limit=2)
demo.launch()

API Access

# Every Gradio app exposes a REST API
# Access docs at http://localhost:7860/?view=api

# Python client
from gradio_client import Client

client = Client("http://localhost:7860")
result = client.predict("Hello!", api_name="/predict")
print(result)

# HuggingFace Spaces
client = Client("username/space-name")
result = client.predict("Hello!", api_name="/predict")

Advanced Usage

Custom CSS/Themes

import gradio as gr

theme = gr.themes.Base(
    primary_hue="indigo",
    secondary_hue="blue",
    neutral_hue="slate",
    font=gr.themes.GoogleFont("Inter"),
)

with gr.Blocks(theme=theme, css=".gradio-container {max-width: 800px}") as demo:
    gr.Markdown("# Styled App")
    gr.Textbox(elem_classes=["custom-class"])

File Processing

import gradio as gr
import pandas as pd

def process_csv(file):
    df = pd.read_csv(file.name)
    summary = df.describe()
    return summary, f"Rows: {len(df)}, Columns: {len(df.columns)}"

demo = gr.Interface(
    fn=process_csv,
    inputs=gr.File(label="Upload CSV", file_types=[".csv"]),
    outputs=[gr.Dataframe(label="Summary"), gr.Textbox(label="Info")]
)

Deployment

# HuggingFace Spaces
# 1. Create Space at huggingface.co/new-space
# 2. Push code with app.py and requirements.txt

# Docker
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "app.py"]

# In app.py, set: demo.launch(server_name="0.0.0.0", server_port=7860)

Troubleshooting

Issue	Solution
Port 7860 in use	Use server_port=7861 in launch()
Share link not working	Check firewall, use share=True
Slow loading	Enable queue(), reduce model size
CORS errors	Set allowed_paths in launch()
File upload fails	Increase upload limit in Gradio config
Memory leak	Clear cache between requests, use @gr.cache
Component not updating	Check output mapping matches function return
SSL errors	Provide valid cert/key paths to launch()

# Debug mode
GRADIO_DEBUG=1 python app.py

# Custom port
python -c "
import gradio as gr
gr.Interface(fn=lambda x: x, inputs='text', outputs='text').launch(server_port=8080)
"