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