Gradio Cheat Sheet

1Install & Interfacehello world

pip install gradio★
Python 3.10+. Bundles the server, the web UI, and gradio_client. CLI: gradio app.py runs with auto-reload for dev.
import gradio as gr def greet(name): return f"Hello {name}!"★
Your app is just a Python function. Gradio builds the UI around its inputs and outputs.
demo = gr.Interface(fn=greet, inputs="textbox", outputs="textbox") demo.launch()★
Interface maps fn's args to input components and its returns to output components. Strings are shorthand for components.
gr.Interface(classify, gr.Image(), gr.Label(num_top_classes=3))
Pass component instances for full control. Order of inputs/outputs matches the function signature/returns.

2Interface optionspolish the demo

gr.Interface(fn, inputs, outputs, title="...", description="...", examples=[["cat.jpg"]])★
examples renders clickable sample inputs; title/description/article add text (Markdown/HTML).
gr.Interface(..., live=True)
Re-run automatically whenever an input changes — no submit button. Great for sliders/filters.
gr.Interface(..., flagging_mode="manual")
Let users flag outputs to a CSV/dataset for later review.
gr.Interface.from_pipeline(hf_pipeline).launch()
One-liner UI for a Hugging Face transformers pipeline — components are inferred from the task.

3Componentsinputs & outputs

gr.Textbox(label="Prompt", lines=3, placeholder="...")★
The workhorse. Common kwargs across components: label, value (default), interactive, visible, info.
gr.Image() · gr.Audio() · gr.Video() · gr.File()★
Media in/out. gr.Image(type="pil"|"numpy"|"filepath") picks how your function receives it.
gr.Slider(0,100,step=1) · gr.Dropdown([...]) · gr.Checkbox() · gr.Number()
Controls. gr.Radio, gr.CheckboxGroup, gr.ColorPicker, gr.DateTime too.
gr.Dataframe() · gr.Label() · gr.JSON() · gr.Plot() · gr.Gallery()
Rich outputs. gr.Markdown/gr.HTML for static text; gr.Chatbot for messages.
gr.Button("Run", variant="primary") · gr.ClearButton()
Buttons trigger events (card 6). variant: primary/secondary/stop.

4Blocks — custom appsfull control

with gr.Blocks() as demo: inp = gr.Textbox() out = gr.Textbox() gr.Button("Go").click(fn, inp, out) demo.launch()★
Blocks is the flexible API: declare components inside a with block, then wire events explicitly. Layout follows code order.
gr.Button("Go").click(fn, inputs=[a,b], outputs=[c])★
Event wiring is the core of Blocks: which function runs, which components feed it, which it updates.
demo.launch() # the Blocks object is the app
A Blocks (and Interface, which subclasses it) launches the same way and supports the same launch kwargs.

5Layout & themingarrange & style

with gr.Row(): a = gr.Textbox(); b = gr.Textbox()★
gr.Row lays out side by side, gr.Column stacks. Nest them for grids. scale= sets relative width.
with gr.Tab("Settings"): ... · with gr.Accordion("Advanced"): ...
Group content into tabs or collapsible accordions. gr.Group visually bundles components.
gr.Blocks(theme=gr.themes.Soft())
Built-in themes: Default, Soft, Monochrome, Glass, Ocode… or build one with gr.themes.Base().
gr.Blocks(css=".gradio-container {max-width: 800px}")
Inject custom CSS (or js=) for fine tuning. elem_id/elem_classes on any component to target it.

6Event listenerswire it up

btn.click(fn, inputs, outputs) · txt.submit(fn, ...)★
Every component exposes event methods: .click, .change, .submit, .input, .select, .upload, .clear.
slider.change(update, slider, out) # fires on every move
.change = value changed (any source); .input = changed by the user specifically.
return gr.update(visible=True, value="...")★
Return gr.update(...) (or a component instance) to change an output's properties, not just its value.
e = btn.click(f1, a, b); e.then(f2, b, c) · .success(...)
Chain events: .then runs after (always), .success only if the prior succeeded. gr.on([...], fn) binds many triggers to one fn.
btn.click(fn, ..., api_name="predict", concurrency_limit=5)
api_name exposes the event as a REST/client endpoint; concurrency_limit caps parallel runs.

7State & sessionsper-user memory

state = gr.State([]) btn.click(fn, [inp, state], [out, state])★
gr.State holds per-session Python objects across events (e.g. a running history). Not shown in the UI.
def fn(x, request: gr.Request): request.username · request.headers
Add a gr.Request param to read the caller's session, headers, query params, and auth user.
gr.BrowserState(default) # persists in localStorage
Survives page reloads on the client. Plain gr.State is per-session and cleared on reload.
# module globals are SHARED across all users -> use gr.Stategotcha
A global list/dict leaks data between visitors. Keep per-user data in gr.State.

8Streaming & progressshow progress

def stream(msg): out = "" for tok in llm(msg): out += tok; yield out★
Yield instead of return to stream partial outputs to the UI — the standard pattern for token-by-token LLM output.
def fn(x, progress=gr.Progress()): for i in progress.tqdm(items): ...
gr.Progress() renders a progress bar; wrap iterables with progress.tqdm(...) or call progress(0.5, desc=...).
gr.Audio(streaming=True) · gr.Image(streaming=True)
Streaming inputs feed live mic/webcam data to your function continuously.

9ChatInterfacechatbots

def respond(message, history): return f"You said: {message}" gr.ChatInterface(respond).launch()★
ChatInterface gives a complete chat UI. Your fn takes (message, history) and returns the reply; history is managed for you.
def respond(message, history): out = "" for tok in llm(message, history): out += tok; yield out★
Yield to stream the assistant's reply. History arrives as OpenAI-style {"role","content"} messages (type="messages", the default).
gr.ChatInterface(respond, type="messages", additional_inputs=[gr.Slider(label="temp")])
additional_inputs adds controls (system prompt, temperature) passed as extra args after history.
gr.ChatInterface(fn, multimodal=True, examples=[...])
multimodal=True adds file/image upload to the chat box. Built-in retry/undo/clear buttons come free.
gr.Chatbot() # the raw component, for use inside Blocks
Need custom layout? Use the gr.Chatbot component directly in Blocks and wire it yourself.

10Launch, share & auth.launch()

demo.launch(share=True)★
Creates a temporary public *.gradio.live URL (up to ~1 week) via a tunnel — instant sharing, no deploy.
demo.launch(server_name="0.0.0.0", server_port=7860)★
0.0.0.0 exposes on your LAN. Port defaults to 7860 (auto-increments if busy). inbrowser=True opens a tab.
demo.launch(auth=("user", "pass")) # or a function
Password-protect the app. auth can be a list of pairs or a fn(username, password) -> bool.
demo.queue(default_concurrency_limit=10).launch()
queue() manages load with a request queue + progress positions. On by default; call it to tune limits.
app = gr.mount_gradio_app(fastapi_app, demo, path="/gradio")
Mount inside an existing FastAPI app for auth/routing/custom endpoints alongside the UI.

11gradio_client & APIcall it in code

from gradio_client import Client client = Client("user/space") # or a URL client.predict("hi", api_name="/predict")★
Any Gradio app is also a programmatic API. The Python gradio_client (and a JS client) call its endpoints.
# every app auto-serves an OpenAPI-style view at /?view=api
Open the app and click Use via API to see endpoint signatures. Name events with api_name= to expose them.
from gradio_client import handle_file client.predict(handle_file("img.png"), api_name="/predict")
Wrap file/media args with handle_file when calling endpoints that expect uploads.

12Deploy & ecosystemhost it

gradio deploy # push to Hugging Face Spaces★
Free hosting on Spaces (Gradio is the HF demo standard). Add a requirements.txt; the CLI walks you through it.
# self-host: any WSGI/ASGI host, Docker, or behind nginx
It's a normal web server — containerize it or mount it in FastAPI (card 10) behind your own infra.
gr.load("models/<hf-model>") · gr.load("spaces/<user/space>")
Instantly build a UI from a hosted HF model or clone another Space's interface.
# custom components: gradio cc create / publish (pip installable)
Build & share your own components with the gradio cc toolkit — a growing ecosystem on the Spaces custom-component hub.

Gradio cheat sheet

Outline

Getting started

Components & layout

Interactivity

Chat

Launch & deploy

Getting Started

Components & Layout

Interactivity

Chat

Launch & Deploy

Worth memorizing