Gradio

On this page 8

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 blockWhat it doesTypical use
gr.InterfaceHigh-level wrapper: one function, listed inputs and outputsSingle-model demos
gr.BlocksLow-level layout with rows, columns, tabs and eventsMulti-step or custom apps
gr.ChatInterfaceReady-made chat UI around a response functionLLM chatbots
ComponentsTyped widgets such as Textbox, Image, Audio, DataframeInputs and outputs
Event listenersMethods such as .click(), .change(), .submit()Wiring actions to functions
gr.StatePer-session value kept on the serverConversation history, counters
Core building blocks of a Gradio application

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 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.

ToolExecution modelBest fitMain limitation
GradioEvent-driven function callsModel demos, chat UIs, SpacesLimited fine-grained layout control
StreamlitFull script rerun per interactionData apps and dashboardsRerun cost with heavy state
Open WebUIFinished chat applicationSelf-hosted LLM chat for teamsNot a general UI toolkit
FastAPI with a custom front endHand-written API and clientProduction productsMuch more engineering effort
Jupyter widgetsNotebook-bound callbacksExploration inside notebooksHard to share outside notebooks
Gradio and alternative ways to put a UI on a model

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.

SituationRecommended optionReason
Quick feedback from a colleagueShare link from launch(share=True)No server setup, expires automatically
Public research demoHugging Face SpacesFree tier, GPU upgrades, versioned repository
Internal tool with private dataSelf-hosted behind a reverse proxyData stays on company infrastructure
Embedding in an existing siteWeb component or iframeReuses the hosted app without rewriting it
Fully client-side demoGradio Lite in the browserRuns Python via WebAssembly, no server
Choosing a deployment option

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.

SymptomCauseFix
Users see each other’s dataGlobal variables used as stateUse gr.State or session-scoped storage
Long waits under loadDefault concurrency of one per eventRaise concurrency_limit, batch, add replicas
Sensitive files reachableOverly broad allowed pathsRestrict file access to required folders
Share link left openPublic tunnel during testingClose the app, use authenticated hosting
App breaks after upgradeMajor version API changesPin the Gradio version in requirements
Frequent problems and how to fix them

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.