Gradio is an open-source Python library for building interactive web interfaces around machine learning models and ordinary Python functions, without writing HTML, CSS or JavaScript. Among AI frameworks & tools in artificial intelligence, it occupies the demo and prototyping layer: a developer declares inputs and outputs, connects them to a function, and Gradio serves a browser application together with an automatically generated API.
The project started in 2019 as a research tool for sharing models with non-programmers and became part of Hugging Face in 2021. It is now the default way to publish interactive demos on Hugging Face Spaces, and it is widely used for internal prototypes, chatbot front ends and quick evaluation tools for language, vision and audio models.
How Gradio turns a Python function into a web app
Gradio works by mapping UI components to function arguments and return values. When a user clicks a button, the browser sends the component values to a Python server, Gradio preprocesses them into Python objects (for example a NumPy array for an image), calls the function, and postprocesses the result back into something the browser can display.
Under the hood, the server side is built on FastAPI and Uvicorn, while the front end is a compiled Svelte application that ships inside the Python package. Calling launch() starts a local server, by default on port 7860, and can optionally create a temporary public share link that tunnels traffic to the developer’s machine.
The table below lists the main building blocks a developer works with.
| Building block | What it does | Typical use |
|---|---|---|
| gr.Interface | High-level wrapper: one function, listed inputs and outputs | Single-model demos |
| gr.Blocks | Low-level layout with rows, columns, tabs and events | Multi-step or custom apps |
| gr.ChatInterface | Ready-made chat UI around a response function | LLM chatbots |
| Components | Typed widgets such as Textbox, Image, Audio, Dataframe | Inputs and outputs |
| Event listeners | Methods such as .click(), .change(), .submit() | Wiring actions to functions |
| gr.State | Per-session value kept on the server | Conversation history, counters |
Interfaces, Blocks and the event model
Gradio offers two levels of abstraction. gr.Interface is declarative and fast: a classifier demo can be written in three or four lines. gr.Blocks exposes an event-driven programming model in which any component event can trigger any function, outputs of one step can feed the next, and visibility of elements can change at runtime.
Functions may be generators, which lets Gradio stream partial results, such as tokens from a language model or progressive image steps. Every event passes through a queue that controls concurrency; by default each event handler runs one call at a time, and the concurrency_limit parameter raises that limit when the model and hardware allow it.
- Streaming outputs suit token-by-token text generation and live audio.
- Batch functions group several queued requests into one model call to raise GPU throughput.
- Session state keeps data per browser tab, while global variables are shared by every user and are a common source of bugs.
The built-in API and client libraries
Every Gradio app is also a programmatic endpoint. Each event listener can be exposed under an API name, and the app footer links to a page that documents how to call it. The official Python client (gradio_client) and JavaScript client (@gradio/client) handle file uploads, queue positions and streaming, so a demo can double as a lightweight inference service.
This dual nature explains much of the adoption in artificial intelligence work: a researcher publishes one Space, and other developers can call the same model from scripts or agents without building a separate backend. The trade-off is that the API mirrors the UI design, so it is less stable and less formally versioned than a purpose-built REST service.
Gradio compared with related tools
Gradio is most often compared with Streamlit, but the two use different execution models. Streamlit reruns the whole script top to bottom on each interaction, while Gradio calls only the function attached to the event. The comparison below places Gradio among neighboring options.
| Tool | Execution model | Best fit | Main limitation |
|---|---|---|---|
| Gradio | Event-driven function calls | Model demos, chat UIs, Spaces | Limited fine-grained layout control |
| Streamlit | Full script rerun per interaction | Data apps and dashboards | Rerun cost with heavy state |
| Open WebUI | Finished chat application | Self-hosted LLM chat for teams | Not a general UI toolkit |
| FastAPI with a custom front end | Hand-written API and client | Production products | Much more engineering effort |
| Jupyter widgets | Notebook-bound callbacks | Exploration inside notebooks | Hard to share outside notebooks |
In practice, teams often use Gradio for the first shareable version of a model and move to a custom front end only when branding, complex navigation or strict API contracts become requirements.
Deploying and sharing Gradio apps
A Gradio app can run locally, on a server or on a managed host, and the right choice depends on audience, data sensitivity and load. The decision table summarizes common situations.
| Situation | Recommended option | Reason |
|---|---|---|
| Quick feedback from a colleague | Share link from launch(share=True) | No server setup, expires automatically |
| Public research demo | Hugging Face Spaces | Free tier, GPU upgrades, versioned repository |
| Internal tool with private data | Self-hosted behind a reverse proxy | Data stays on company infrastructure |
| Embedding in an existing site | Web component or iframe | Reuses the hosted app without rewriting it |
| Fully client-side demo | Gradio Lite in the browser | Runs Python via WebAssembly, no server |
For self-hosting, Gradio can be mounted inside a FastAPI application, which lets teams add their own middleware, logging and single sign-on. The built-in auth parameter provides only basic username and password protection and is not a substitute for proper identity management.
Limitations, risks and common mistakes
Gradio optimizes for speed of building, not for full control, and several problems recur in real projects. The most serious are security exposure and scaling misconceptions, because a demo that works for one user can fail under concurrent traffic.
| Symptom | Cause | Fix |
|---|---|---|
| Users see each other’s data | Global variables used as state | Use gr.State or session-scoped storage |
| Long waits under load | Default concurrency of one per event | Raise concurrency_limit, batch, add replicas |
| Sensitive files reachable | Overly broad allowed paths | Restrict file access to required folders |
| Share link left open | Public tunnel during testing | Close the app, use authenticated hosting |
| App breaks after upgrade | Major version API changes | Pin the Gradio version in requirements |
Major releases, such as Gradio 4 and Gradio 5, changed component parameters and internal behavior, so pinning versions matters for long-lived apps. Gradio 5 also introduced server-side rendering and security hardening after an external audit, which reflects how often demos end up exposed to the internet.
A plain-language summary
Gradio is a shortcut for showing an AI model to other people. Normally, a model lives inside code that only programmers can run. Gradio puts a simple web page in front of it, with boxes to type into, buttons to press and places to upload pictures or sound.
Think of it as a shop window for a model. The kitchen stays the same, but now anyone passing by can see what it makes and try it. The key point is that Gradio is built for fast sharing and testing, not for running a large commercial product on its own.
An example from practice
A small research group at a university hospital fine-tunes a speech recognition model for medical dictation. Clinicians need to test it, but none of them use Python. A data scientist writes a Gradio Blocks app of about 60 lines with a microphone input, a transcript box, a field for corrections and a button that saves feedback.
Because the recordings contain patient information, the team does not use a public share link. It deploys the app on an internal server behind the hospital’s reverse proxy and single sign-on, sets a concurrency limit of four on a single GPU and pins the Gradio version. Over three weeks, twelve clinicians submit about 400 corrected transcripts, which the team uses to measure word error rate and prioritize the next round of fine-tuning. The outcome is clinical feedback within days instead of the months a custom application would have required.