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 INLINECODE10
• INLINECODE11 on a function serializes calls — use for GPU-bound inference that can't parallelize
• INLINECODE12 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
• INLINECODE14 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
• INLINECODE21 returns a PIL Image, type="numpy" returns an array, type="filepath" returns a path — inconsistent inputs break functions
• INLINECODE24 expects list of tuples [(user, bot), ...] — returning just strings doesn't render
• INLINECODE26 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
• INLINECODE30 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
• INLINECODE32 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
• INLINECODE38 on a function polls every 5 seconds — but it holds connections open, scale carefully
• INLINECODE39 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
• INLINECODE42 with max_batch_size=N groups concurrent requests — essential for GPU throughput