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

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

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

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

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

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

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

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

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