Gradio Tutorial
Learn Gradio step by step: 37 lessons in 9 chapters with examples, quizzes, diagrams and projects.
Start learning →
of lessons completed
Getting Started
- What Is Gradio? Learn what Gradio is, what problems it solves, how a Python function becomes a web app, and when to choose it over Streamlit, Flask or a full front end.
- Install Gradio and Build Your First App Install Gradio in a virtual environment, write a first Interface, run it, and learn what the page shows, which port it uses and how to fix common start-up errors.
- How Gradio Works Under the Hood Follow a Gradio request from the browser to your function and back. Learn about the FastAPI server, the queue, preprocessing and postprocessing, and the generated API.
- Launch Options, Notebooks and Reload Mode Master Gradio's launch() options: server name and port, share links, authentication, running in Jupyter or Colab, auto-reload for development, and clean shutdown.
Interfaces and Components
- The Interface Class in Depth Understand gr.Interface fully: fn, inputs, outputs, multiple values, return tuples, titles, articles, buttons, live mode and how to choose between Interface and Blocks.
- Text and Number Inputs Learn Gradio's text components: Textbox options, Number, Markdown, HTML, Code, JSON and Label. See which Python types they give your function and how to validate input.
- Images, Audio, Video and Files Work with Gradio media components: Image type options, Audio as (sample rate, array), Video, File, upload limits and the temporary-file rules behind them.
- Choices, Sliders and Dates Choose the right Gradio selection component: Dropdown, Radio, CheckboxGroup, Checkbox, Slider, ColorPicker and DateTime, with the Python value each one returns.
- Examples, Flagging and API Names Add clickable examples to a Gradio app, cache their outputs, collect user feedback with flagging, and name your API endpoints so clients can call them reliably.
- Dataframes and Plots Show tables and charts in Gradio: Dataframe as input and output, built-in LinePlot, BarPlot and ScatterPlot, and the Matplotlib route. Learn the data shapes each one needs.
Blocks and Layouts
- Blocks Basics Learn gr.Blocks, Gradio's low-level API: build a page with a context manager, place components, attach click handlers, and understand how it relates to Interface.
- Rows, Columns, Tabs and Accordions Control a Gradio page with layout blocks: Row, Column with scale and min_width, Tabs, Accordion, Group, Sidebar and nesting. Includes responsive behaviour and common layout mistakes.
- Themes and Custom CSS Style a Gradio app: built-in themes, theme builder variables, light and dark mode, custom CSS with elem_id and elem_classes, and custom JavaScript. Includes a version note.
- Dynamic UI: Visibility, Updates and render Make a Gradio page change as users interact: toggle visibility, return updated component properties, swap choices, and build components from data with the @gr.render decorator.
State and Events
- Event Listeners: click, change, submit, load and more Learn every common Gradio event: click, change, input, submit, select, load, focus and blur. Understand inputs, outputs, triggers lists, gr.on and per-event options.
- Event Chaining with then, success and Timers Run Gradio steps in order with .then(), .success() and .failure(), refresh data with gr.Timer, and split long work into stages. Includes error handling and race condition tips.
- Session State with gr.State Keep data between Gradio events safely: why globals are shared between all users, how gr.State gives each session its own value, and when to use BrowserState or a database.
- Generators and Streaming Output Stream results from a Gradio function with yield, show progress with gr.Progress, stream audio and webcam input, and cancel long jobs cleanly. Includes runnable generator stand-ins.
- Queue, Concurrency and Rate Limits Tune Gradio's queue: default_concurrency_limit, per-event limits, max_size, batching, status updates and rate limiting. Learn how many users an app can serve and why.
Models and Demos
- Wrapping a Model in a Gradio Demo Learn the load-once, predict-many pattern for putting any model behind a Gradio interface: global loading, preprocessing, postprocessing, labels and confidence scores.
- Image and Audio Demos Build Gradio demos for pictures and sound: gr.Image types, gr.Audio formats, numpy arrays, file paths, sample rates, plus runnable pixel and waveform stand-ins.
- Text and NLP Demos Build Gradio demos for language tasks: classification, summarization, named entities with HighlightedText, translation and keyword counts. Includes runnable tokenizer stand-ins.
- Loading Hub Models and Spaces Use gr.load, gr.Interface.from_pipeline and the Hugging Face Hub to build demos from existing models, remix Spaces and understand inference providers, with a runnable registry stand-in.
- Chatbots with ChatInterface Build a chat UI with gr.ChatInterface: the fn(message, history) signature, messages format, streaming replies, system prompts, extra inputs and a runnable chat-loop stand-in.
- Streaming Output and Progress Bars Show results while work is still running: generator functions, gr.Progress and progress.tqdm, streaming outputs and live inputs, cancelling, with runnable generator stand-ins.
Sharing and Deployment
- Capacity Planning, Share Links and Going Public Estimate how many visitors a Gradio app can serve, simulate waiting lines and bounded queues, and learn what share=True, server_name and launch options expose before you go public.
- Deploying Gradio to Hugging Face Spaces Publish a Gradio app on Hugging Face Spaces: app.py, requirements.txt, README metadata, secrets, hardware, plus other hosting options and a runnable config checker.
- Authentication, Secrets and Security Protect a Gradio app: login with auth, OAuth sign-in, environment secrets, upload limits, allowed_paths, input validation and safe file handling, with runnable stand-ins.
- The Gradio API and Python Client Every Gradio app is also an API. Learn api_name, the Python and JavaScript clients, the two-step HTTP call protocol, file inputs and Server-Sent Events, with a runnable mock server.
Custom Components
- Custom Components: How They Work Understand Gradio custom components: the gradio cc workflow, backend class with preprocess and postprocess, Svelte frontend, data models and publishing, with a runnable component stand-in.
- Themes, CSS and JavaScript Restyle a Gradio app with built-in themes, theme.set variables, elem_id and elem_classes, custom CSS and head scripts, plus a runnable contrast checker and CSS generator.
Testing and Patterns
- Testing Gradio Apps Test Gradio apps in layers: pure function tests with pytest, parametrized cases, mocking slow models, client-based API tests and smoke checks, with runnable test-runner stand-ins.
- Structuring Larger Gradio Apps Organize a growing Gradio project: separate logic from UI, build tabs from functions, use gr.render, TabbedInterface, mount in FastAPI and share config, with runnable registry stand-ins.
- Errors, Notifications and Performance Handle failures gracefully in Gradio with gr.Error, gr.Warning and gr.Info, validate inputs, cache examples and results, and measure slow steps, with runnable stand-ins.
Projects and Practice
- Project: Sentiment Analyzer Build a complete sentiment analyzer: a lexicon scorer with negation, highlighted words, a batch table, and the Blocks layout, tests and deployment files, with runnable core logic.
- Project: Image Filter Studio Build an image filter app: brightness, contrast, threshold, blur and flip on pixel grids, a pipeline of steps, ASCII preview and the Gradio layout with sliders, with runnable pixel code.
- Project: Chat Assistant with Memory Build a chat assistant with Gradio Blocks: per-session memory with gr.State, slash commands, history trimming, streaming replies and a pluggable model, plus practice exercises.