Gradio¶

This work is licensed under a Creative Commons Attribution 4.0 International License.
What is Gradio?¶
Gradio is an open-source Python library that makes it easy to create interactive web interfaces for machine learning models, data science applications, and AI tools. With just a few lines of code, you can build shareable demos that allow users to interact with your work through a web browser.
Why Gradio Matters for Researchers:
- Share your work: Create interactive demos of your research for papers, presentations, or collaborators
- No web development required: Build interfaces using only Python - no HTML, CSS, or JavaScript needed
- Rapid prototyping: Test and iterate on AI applications quickly
- Accessibility: Make your models accessible to non-technical colleagues and stakeholders
- Reproducibility: Package your research into interactive, shareable applications
Gradio and Hugging Face
Gradio is developed by Hugging Face and integrates seamlessly with the Hugging Face ecosystem. Most interactive demos you see on Hugging Face Spaces are built with Gradio. This makes it easy to deploy your Gradio apps to the cloud with a single command.
Installation¶
Basic Installation¶
Installation with Additional Dependencies¶
For working with Hugging Face models:
For working with audio and images:
Verify Installation¶
As of early 2026, the current stable version is Gradio 5.x.
Quick Start: Your First Gradio App¶
Let's build a simple interface that takes text input and returns a greeting:
import gradio as gr
def greet(name):
return f"Hello, {name}! Welcome to Gradio."
# Create the interface
demo = gr.Interface(
fn=greet, # The function to wrap
inputs="text", # Input type
outputs="text", # Output type
title="Simple Greeter",
description="Enter your name to receive a greeting."
)
# Launch the app
demo.launch()
When you run this code, Gradio will:
- Start a local web server (typically at
http://127.0.0.1:7860) - Open your default browser to display the interface
- Provide a shareable link if you set
share=True
Running in Jupyter Notebooks
Gradio works seamlessly in Jupyter notebooks. The interface will display inline within the notebook cell. This is perfect for iterative development and demonstrations.
Core Concepts¶
The Interface Class¶
gr.Interface is the simplest way to create a Gradio app. It wraps any Python function with a user interface:
gr.Interface(
fn=your_function, # Required: The function to call
inputs=input_components, # Required: Input component(s)
outputs=output_components, # Required: Output component(s)
title="App Title", # Optional: Display title
description="Description", # Optional: Help text
examples=[["example1"], ["example2"]] # Optional: Example inputs
)
Common Input/Output Components¶
Gradio provides many component types:
| Component | Description | Example Use |
|---|---|---|
gr.Textbox |
Text input/output | Questions, prompts, responses |
gr.Number |
Numeric input | Parameters, scores |
gr.Slider |
Range selection | Temperature, confidence thresholds |
gr.Dropdown |
Selection from options | Model selection, categories |
gr.Checkbox |
Boolean toggle | Enable/disable features |
gr.Image |
Image upload/display | Vision models, image processing |
gr.Audio |
Audio upload/playback | Speech recognition, synthesis |
gr.File |
File upload | Document processing |
gr.Dataframe |
Tabular data | Data analysis results |
gr.Plot |
Charts and graphs | Visualizations |
gr.Markdown |
Formatted text | Instructions, results |
Building Practical Applications¶
Example 1: Text Summarization Interface¶
This example creates a tool for summarizing academic papers or long documents:
import gradio as gr
def summarize_text(text, max_length, style):
"""
A placeholder summarization function.
In practice, you would connect this to an LLM.
"""
# Simulate summarization
word_count = len(text.split())
summary = f"[{style} summary of {word_count} words, max {max_length} words]"
# In real use, you would call an API or model here:
# from transformers import pipeline
# summarizer = pipeline("summarization")
# result = summarizer(text, max_length=max_length)
return summary
demo = gr.Interface(
fn=summarize_text,
inputs=[
gr.Textbox(
label="Text to Summarize",
placeholder="Paste your article, paper abstract, or document here...",
lines=10
),
gr.Slider(
minimum=50,
maximum=500,
value=150,
step=10,
label="Maximum Summary Length (words)"
),
gr.Dropdown(
choices=["Brief", "Detailed", "Technical", "Simplified"],
value="Brief",
label="Summary Style"
)
],
outputs=gr.Textbox(label="Summary", lines=5),
title="Academic Text Summarizer",
description="Paste text from papers, articles, or documents to generate a summary.",
examples=[
["Machine learning is a subset of artificial intelligence that enables systems to learn and improve from experience without being explicitly programmed.", 100, "Brief"],
]
)
demo.launch()
Example 2: Image Classification with Hugging Face Models¶
This example demonstrates how to connect Gradio to a Hugging Face model. For more on accessing Hugging Face models, see the Hugging Face documentation.
import gradio as gr
from transformers import pipeline
# Load a pre-trained image classification model from Hugging Face
# See https://huggingface.co/models?pipeline_tag=image-classification
classifier = pipeline("image-classification", model="google/vit-base-patch16-224")
def classify_image(image):
"""Classify an uploaded image and return top predictions."""
if image is None:
return "Please upload an image."
# Run classification
predictions = classifier(image)
# Format results
results = "\n".join([
f"{pred['label']}: {pred['score']:.2%}"
for pred in predictions[:5]
])
return results
demo = gr.Interface(
fn=classify_image,
inputs=gr.Image(type="pil", label="Upload an Image"),
outputs=gr.Textbox(label="Classification Results", lines=6),
title="Image Classifier",
description="Upload an image to classify its contents using a Vision Transformer model from Hugging Face.",
examples=[
["https://upload.wikimedia.org/wikipedia/commons/thumb/3/3a/Cat03.jpg/1200px-Cat03.jpg"]
]
)
demo.launch()
First Run Download
The first time you run this code, the transformers library will download the model from Hugging Face. This may take a few minutes depending on your internet connection. Subsequent runs will use the cached model.
Example 3: Question Answering with Context¶
This example creates a research assistant that answers questions based on provided context:
import gradio as gr
from transformers import pipeline
# Load a question-answering model
qa_model = pipeline("question-answering", model="deepset/roberta-base-squad2")
def answer_question(context, question):
"""Answer a question based on the provided context."""
if not context or not question:
return "Please provide both context and a question."
result = qa_model(question=question, context=context)
answer = result['answer']
confidence = result['score']
return f"**Answer:** {answer}\n\n**Confidence:** {confidence:.2%}"
demo = gr.Interface(
fn=answer_question,
inputs=[
gr.Textbox(
label="Context",
placeholder="Paste the text passage that contains the answer...",
lines=8
),
gr.Textbox(
label="Question",
placeholder="Ask a question about the text above..."
)
],
outputs=gr.Markdown(label="Answer"),
title="Research Document Q&A",
description="Paste a passage from a paper or document, then ask questions about it.",
examples=[
[
"The transformer architecture was introduced in the paper 'Attention Is All You Need' by Vaswani et al. in 2017. It revolutionized natural language processing by replacing recurrent neural networks with self-attention mechanisms, enabling much faster training through parallelization.",
"When was the transformer architecture introduced?"
],
[
"CRISPR-Cas9 is a genome editing technology that allows scientists to make precise changes to DNA. It works by using a guide RNA to direct the Cas9 enzyme to a specific location in the genome, where it makes a cut. The cell's natural repair mechanisms then make the desired edit.",
"How does CRISPR-Cas9 work?"
]
]
)
demo.launch()
Example 4: Multi-Modal Interface with Blocks¶
For more complex layouts, use gr.Blocks instead of gr.Interface:
import gradio as gr
def analyze_data(file, analysis_type):
"""Placeholder for data analysis function."""
if file is None:
return "Please upload a file.", None
# In practice, you would process the file here
# import pandas as pd
# df = pd.read_csv(file.name)
summary = f"Analysis type: {analysis_type}\nFile uploaded successfully."
# Generate a placeholder plot
import matplotlib.pyplot as plt
import numpy as np
fig, ax = plt.subplots()
x = np.linspace(0, 10, 100)
ax.plot(x, np.sin(x), label='Sample Data')
ax.set_xlabel('X axis')
ax.set_ylabel('Y axis')
ax.set_title(f'{analysis_type} Results')
ax.legend()
return summary, fig
# Create a more complex layout with Blocks
with gr.Blocks(title="Research Data Analyzer") as demo:
gr.Markdown("# Research Data Analyzer")
gr.Markdown("Upload your data file and select an analysis type.")
with gr.Row():
with gr.Column(scale=1):
file_input = gr.File(label="Upload Data File (CSV, Excel)")
analysis_dropdown = gr.Dropdown(
choices=["Descriptive Statistics", "Correlation Analysis",
"Trend Analysis", "Outlier Detection"],
label="Analysis Type",
value="Descriptive Statistics"
)
analyze_btn = gr.Button("Run Analysis", variant="primary")
with gr.Column(scale=2):
output_text = gr.Textbox(label="Analysis Summary", lines=5)
output_plot = gr.Plot(label="Visualization")
analyze_btn.click(
fn=analyze_data,
inputs=[file_input, analysis_dropdown],
outputs=[output_text, output_plot]
)
demo.launch()
Connecting to Large Language Models¶
Using Hugging Face Inference API¶
Connect to models hosted on Hugging Face without downloading them locally:
import gradio as gr
from huggingface_hub import InferenceClient
# Initialize the client (requires HF_TOKEN environment variable or explicit token)
# See the Hugging Face documentation for setting up authentication:
# https://huggingface.co/docs/huggingface_hub/quick-start#authentication
client = InferenceClient()
def chat_with_model(message, history, system_prompt, model_name):
"""Chat with a Hugging Face model via the Inference API."""
messages = [{"role": "system", "content": system_prompt}]
# Add conversation history
for human, assistant in history:
messages.append({"role": "user", "content": human})
messages.append({"role": "assistant", "content": assistant})
# Add current message
messages.append({"role": "user", "content": message})
# Generate response
response = client.chat_completion(
model=model_name,
messages=messages,
max_tokens=500,
temperature=0.7
)
return response.choices[0].message.content
demo = gr.ChatInterface(
fn=chat_with_model,
additional_inputs=[
gr.Textbox(
value="You are a helpful research assistant specializing in academic writing.",
label="System Prompt",
lines=2
),
gr.Dropdown(
choices=[
"meta-llama/Llama-3.2-3B-Instruct",
"mistralai/Mistral-7B-Instruct-v0.3",
"Qwen/Qwen2.5-7B-Instruct"
],
value="meta-llama/Llama-3.2-3B-Instruct",
label="Model"
)
],
title="Research Assistant Chatbot",
description="Chat with open-source LLMs from Hugging Face. Select a model and customize the system prompt."
)
demo.launch()
API Rate Limits
The Hugging Face Inference API has rate limits for free users. For heavy usage, consider a Hugging Face Pro subscription or running models locally with Ollama.
Using Local Models with Ollama¶
Connect Gradio to locally-running models via Ollama:
import gradio as gr
import requests
import json
def chat_with_ollama(message, history, model_name):
"""Chat with a local Ollama model."""
# Build conversation context
full_prompt = ""
for human, assistant in history:
full_prompt += f"User: {human}\nAssistant: {assistant}\n"
full_prompt += f"User: {message}\nAssistant:"
# Call Ollama API
response = requests.post(
"http://localhost:11434/api/generate",
json={
"model": model_name,
"prompt": full_prompt,
"stream": False
}
)
if response.status_code == 200:
return response.json()["response"]
else:
return f"Error: {response.status_code}"
demo = gr.ChatInterface(
fn=chat_with_ollama,
additional_inputs=[
gr.Dropdown(
choices=["llama3.2", "mistral", "qwen2.5", "deepseek-r1:8b"],
value="llama3.2",
label="Local Model (Ollama)"
)
],
title="Local AI Chat",
description="Chat with AI models running locally on your machine via Ollama."
)
demo.launch()
Deploying to Hugging Face Spaces¶
Hugging Face Spaces provides free hosting for Gradio applications. This is the easiest way to share your work with collaborators or the public.
Method 1: Deploy from the Command Line¶
-
Install the Hugging Face CLI:
-
Log in to Hugging Face:
-
Create your app file (
app.py): -
Create a
requirements.txtfile: -
Deploy using the Gradio CLI:
Follow the prompts to name your Space and configure settings.
Method 2: Create a Space on the Web¶
- Go to huggingface.co/new-space
- Choose "Gradio" as the SDK
- Name your Space and set visibility (public or private)
- Upload your
app.pyandrequirements.txtfiles - The Space will automatically build and deploy
Method 3: Use the Share Feature¶
For quick sharing without permanent hosting:
This creates a temporary public URL (valid for 72 hours) that anyone can access.
Space Hardware
Free Hugging Face Spaces run on basic CPU hardware. For GPU-accelerated models, you can upgrade to paid hardware tiers. See Hugging Face Spaces documentation for options.
Best Practices¶
For Academic Applications¶
- Add clear documentation: Use
gr.Markdownto explain what your tool does and how to use it - Provide examples: Include representative examples that demonstrate the tool's capabilities
- Handle errors gracefully: Validate inputs and provide helpful error messages
- Include citations: Add references to papers or methods your tool is based on
Performance Tips¶
-
Cache expensive operations:
-
Use queuing for concurrent users:
-
Stream long outputs:
Security Considerations¶
- Never expose API keys in your code - use environment variables
- Be cautious with file uploads - validate file types and sizes
- Consider rate limiting for public applications
- Review Gradio's security guidelines
Further Resources¶
- Gradio Documentation: https://www.gradio.app/docs/
- Gradio Guides: https://www.gradio.app/guides/
- Hugging Face Spaces: https://huggingface.co/spaces
- Example Spaces Gallery: https://huggingface.co/spaces (browse for inspiration)
- Gradio GitHub: https://github.com/gradio-app/gradio
Related Workshop Materials¶
- Hugging Face: Learn how to find and use pre-trained models for your Gradio apps
- Ollama: Run local models that can power your Gradio interfaces
- Jupyter AI: Integrate AI assistants into your notebook workflows
- Code Execution: Understand safe practices for running code in AI applications