Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 37 ยท Getting Started

How Gradio Works Under the Hood

Follow a Gradio request from the browser to your function and back. Learn about the FastAPI server, the queue, preprocessing and postprocessing, and the generated API.

You do not need to know how Gradio works internally to use it, but a mental model makes every later lesson easier: why component values arrive as NumPy arrays, why slow functions get a queue, why a "Use via API" page exists, and why your function should never depend on global variables. This lesson follows one click from the browser to your function and back.

The architecture

flowchart LR
    B["Browser UI<br/>(Svelte front end)"] -->|"event + input values"| Q["Queue"]
    Q --> P["Preprocess<br/>(component to Python value)"]
    P --> F["Your function"]
    F --> PP["Postprocess<br/>(Python value to component)"]
    PP -->|"result"| B
    C["Python or JS client"] -->|"same API"| Q

One request: the same path serves the web page and API clients.

A Gradio app is two programs. The front end is a compiled JavaScript application served to the browser; it draws the components and sends events. The back end is a Python web server (built on FastAPI and Starlette) that keeps the app definition, runs your functions and streams results back. When you call launch(), the back end starts, and the front end is downloaded by whoever opens the URL.

What happens when you press Submit

  1. The browser sends an event. The payload names the function (an internal index and, if set, an api_name) and carries the values of all input components in order.
  2. The queue accepts the job. Gradio puts every event in a queue by default. It can run several jobs at once (a concurrency limit) and tells the browser the position in line.
  3. Preprocessing. Each input value is converted into the Python type your function expects. An image component, for example, sends a file reference, and preprocessing loads it into a NumPy array (or a PIL image or file path, depending on the type argument).
  4. Your function runs, in a worker thread, so a slow model does not block the server loop.
  5. Postprocessing. The return value is converted back to what the component can display. A NumPy array becomes an image file, a dictionary becomes JSON, a pandas DataFrame becomes table data.
  6. The result travels back over a streaming connection (server-sent events), so progress and generator output can arrive in pieces.

Why this matters to you:

  • Components, not you, decide the Python type your function receives. Read the component's documentation for its type and format options.
  • Anything your function returns must be convertible by the output component. Returning an unsupported type causes a postprocess error that is not visible in your function.
  • The function is called from a thread. Do not store per-user data in module-level variables (see session state).

The API comes for free

Because the UI itself talks to the server using a documented protocol, a script can do the same. The page footer's Use via API panel lists each endpoint with copy-ready code. The official Python client works like this (read-only; it needs a running app):

Python
from gradio_client import Client

client = Client("http://127.0.0.1:7860/")
result = client.predict("hello", api_name="/predict")
print(result)          # HELLO!

api_name is the endpoint name. Interface registers its function as /predict. In event listeners you will name endpoints yourself.

There is also a JavaScript client, and the REST protocol itself can be called with curl. The front end is not special: it uses the same API.

Components carry two jobs

Every component is both a widget in the browser and a converter on the server. That is the pair of functions preprocess and postprocess:

Component Browser widget Python value (default)
Textbox text field str
Number numeric field float or int
Checkbox tick box bool
Image upload / webcam canvas numpy.ndarray (H x W x 3)
Dataframe editable table pandas.DataFrame

Custom components (see the chapter on custom components) are exactly new pairs of widget and converter.

Stand-in 1: preprocess, function, postprocess

This stand-in models the pipeline with plain Python. The "browser" speaks only in strings, so each side converts.

Python Stand-in: the request pipeline

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice that your function (tip) sees real Python numbers and booleans. The strings only exist at the edges. That is exactly the point of preprocessing.

Stand-in 2: a queue with a concurrency limit

Here an asyncio queue runs three simulated jobs, two at a time. It is a stand-in for the idea, not Gradio's scheduler.

Python Stand-in: queue with concurrency limit

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

With a limit of two, jobs a and b start together and c waits for a free slot. In real Gradio you tune this with default_concurrency_limit and per-event concurrency_limit (see queue and concurrency).

Common beliefs that are wrong

  • "Gradio re-runs my script on every click." No. Your script runs once; only the function runs per event. That is the key difference from Streamlit.
  • "Each browser tab gets its own Python process." No. All users share one process and one set of globals, which is why session state exists.
  • "The front end is Python." No. Python describes the app; a prebuilt JavaScript front end draws it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which step converts a file reference from the browser into a NumPy array for your function?

    Preprocessing turns the component payload into the Python type your function expects. Postprocessing does the reverse for the output.
  2. 2. How many times does Gradio run your top-level script when a user clicks Submit?

    The script runs once at start. Events call only the functions you attached.
  3. 3. What is the purpose of the queue?

    The queue protects slow functions, reports position in line and supports streaming results.
  4. 4. Why is the 'Use via API' panel available?

    The UI itself is a client of the server's API, so scripts can call the same endpoints.

Summary

  • A Gradio app is a Python back end (FastAPI) plus a prebuilt JavaScript front end.
  • Events go through a queue, then preprocess, your function, postprocess and back.
  • Components own the conversion between browser data and Python values.
  • The UI and API share one protocol, so every app is also an API.
  • Your script runs once; users share one process, so plan for shared state.

Next: Launch Options, Notebooks and Reload Mode