Gradio

---

name: Gradio description: Build and deploy ML demo interfaces with proper state management, queuing, and production patterns. metadata: {"clawdbot":{"emoji":"🎨","requires":{"bins":["python3"]},"os":["linux","darwin","win32"]}}

---

Gradio Patterns

Interface vs Blocks

gr.Interface is for single-function demos — use gr.Blocks for anything with multiple steps, conditional UI, or custom layout

Blocks gives you .click(), .change(), .submit() event handlers — Interface only has one function

Mixing Interface inside Blocks works but creates confusing state — pick one pattern per app

State Management

gr.State() creates per-session state — it resets when the user refreshes the page

State values must be JSON-serializable or Gradio silently drops them — no custom classes without serialization

Pass State as both input AND output to persist changes: fn(state) -> state — forgetting the output loses updates

Global variables shared across users cause race conditions — always use gr.State() for user-specific data

Queuing and Concurrency

Without .queue(), long-running functions block all other users — always call demo.queue() before .launch()

concurrency_limit=1 on a function serializes calls — use for GPU-bound inference that can't parallelize

max_size in queue limits waiting users — without it, memory grows unbounded under load

Generator functions with yield enable streaming — but they hold a queue slot until complete

File Handling

Uploaded files are temp paths that get deleted after the request — copy them if you need persistence

gr.File(type="binary") returns bytes, type="filepath" returns a string path — mismatching causes silent failures

Return gr.File(value="path/to/file") for downloads, not raw bytes — the component handles content-disposition headers

File uploads have a default 200MB limit — set max_file_size in launch() to change it

Component Traps

gr.Dropdown(value=None) with allow_custom_value=False crashes if the user submits nothing — set a default or make it optional

gr.Image(type="pil") returns a PIL Image, type="numpy" returns an array, type="filepath" returns a path — inconsistent inputs break functions

gr.Chatbot expects list of tuples [(user, bot), ...] — returning just strings doesn't render

visible=False components still run their functions — use gr.update(interactive=False) to disable without hiding

Authentication

auth=("user", "pass") is plaintext in code — use auth=auth_function for production with proper credential checking

Auth applies to the whole app — there's no per-route or per-component auth without custom middleware

share=True with auth still exposes auth to Gradio's servers — use your own tunnel for sensitive apps

Deployment

share=True creates a 72-hour public URL through Gradio's servers — not for production, just demos

Environment variables in local dev don't exist in Hugging Face Spaces — use Spaces secrets or the Settings UI

server_name="0.0.0.0" to accept external connections — default 127.0.0.1 only allows localhost

Behind a reverse proxy, set root_path="/subpath" or assets and API routes break

Events and Updates

Return gr.update(value=x, visible=True) to modify component properties — returning just the value only changes value

Chain events with .then() for sequential operations — parallel .click() handlers race

every=5 on a function polls every 5 seconds — but it holds connections open, scale carefully

trigger_mode="once" prevents double-clicks from firing twice — default allows rapid duplicate submissions

Performance

cache_examples=True pre-computes example outputs at startup — speeds up demos but increases load time

Large model loading in the function runs per-request — load in global scope or use gr.State with initialization

batch=True with max_batch_size=N groups concurrent requests — essential for GPU throughput