CtrlK
Gradio is an open-source Python library that allows developers to build interactive web interfaces for machine learning models, APIs, and arbitrary Python functions with minimal code. Originally created in 2019 by Abubakar Abid during his PhD at Stanford, Gradio was acquired by Hugging Face in December 2021 and has since become one of the most widely used tools for creating and sharing ML demos. Licensed under the Apache 2.0 license, Gradio is completely free to use and has accumulated over 42,000 stars on GitHub as of early 2026, with millions of monthly downloads from PyPI.
Gradio was born out of a practical problem. In early 2019, Abubakar Abid was in the third year of his PhD in applied machine learning at Stanford University. He and his labmates had trained a computer vision model that could predict patient biomarkers from ultrasound images of the heart with accuracy comparable to a cardiologist. However, when Abid tried to share the model with a collaborating doctor who did not know Python, he realized there was no simple way to let non-technical users interact with ML models.
This frustration led Abid to recruit his Stanford housemates, Ali Abdalla, Ali Abid, and Dawood Khan, to build a tool that could wrap any Python function in a shareable web interface. The first version of Gradio was released in 2019, initially focused on computer vision tasks before expanding to cover text, audio, video, and other modalities.
The founding team participated in the PearX S19 accelerator cohort, a 14-week program run by Pear VC. During this period, they ran pilots with NLP companies in the legal and financial sectors, and secured early clients including Wells Fargo and TD Bank. The team had Stanford Professor James Zou as an academic advisor, and the cofounders brought experience from organizations like Tesla and Google.
For a period, the team explored enterprise SaaS approaches for data labeling and collection. In early 2021, they returned to their original open-source mission after noticing that the Gradio library had accumulated hundreds of GitHub stars even while unmaintained. This pivot proved decisive: the library's simplicity and usefulness attracted a rapidly growing community of ML practitioners.
In the summer of 2021, Julien Chaumond, CTO of Hugging Face, reached out to the Gradio team via their website. The two teams began collaborating on what would become Hugging Face Spaces, a platform for hosting interactive ML demos. On December 21, 2021, Gradio's team of five engineers (the four cofounders plus Ahsen Khaliq, who joined in 2021) signed the acquisition papers. By that time, more than 300,000 demos had been built with Gradio.
The acquisition aligned the missions of both organizations: Gradio aimed to democratize ML model sharing through easy-to-build GUIs, while Hugging Face sought to make state-of-the-art models accessible through simple code. Gradio continued to operate as an independent open-source library under the Hugging Face umbrella, with Abid serving as machine learning team lead at Hugging Face.
Gradio is organized around three main abstractions that accommodate different levels of complexity: Interface, ChatInterface, and Blocks.
The gr.Interface class is the highest-level abstraction in Gradio. It wraps any Python function in a web UI by specifying three required parameters:
| Parameter | Description |
|---|---|
fn | The Python function to wrap with a user interface |
inputs | One or more Gradio components to use for input (e.g., "text", "image", "audio") |
outputs | One or more Gradio components to use for output |
A minimal example looks like this:
import gradio as gr
def greet(name, intensity):
return "Hello, " + name + "!" * int(intensity)
demo = gr.Interface(
fn=greet,
inputs=["text", "slider"],
outputs=["text"],
)
demo.launch()
This code launches a local web server with a text input, a slider, and a text output. The number of input components must match the number of function arguments, and the number of output components must match the number of return values. Components can be specified as string shortcuts (like "text") or as class instances (like gr.Textbox(label="Your Name")) for finer control over appearance and behavior.
gr.ChatInterface is a specialized high-level class designed for building chatbot applications. It provides a pre-built chat UI with message history, input box, and submit button. Developers only need to supply a function that takes a message and chat history and returns a response. This class works well with large language models, supporting streaming responses and tool usage display. For servers compatible with the OpenAI API (such as Ollama), gr.load_chat() can spin up a chat interface in a single line of code.
The gr.Blocks class is the low-level API that provides full control over layout, data flow, and interactivity. Unlike Interface, which arranges inputs on the left and outputs on the right, Blocks lets developers place components anywhere on the page using layout containers:
| Layout Container | Purpose |
|---|---|
gr.Row() | Arranges child components horizontally |
gr.Column() | Arranges child components vertically (default) |
gr.Tab() | Creates tabbed sections |
gr.Accordion() | Creates collapsible sections |
gr.Group() | Groups components visually without extra spacing |
Blocks also supports multiple event listeners, allowing outputs from one function to serve as inputs to another. Components can be updated dynamically based on user interaction, and visibility can be toggled programmatically. The scale and min_width parameters on components control how space is distributed within rows.
Gradio includes more than 30 pre-built components that correspond to common data types in machine learning. Each component can function as an input, an output, or both.
| Component | Data Type | Typical Use |
|---|---|---|
gr.Textbox | String | Text input and output |
gr.Number | Numeric | Numeric input and output |
gr.Slider | Numeric | Bounded numeric input with a slider control |
gr.Checkbox | Boolean | Toggle input |
gr.Dropdown | String | Selection from a list of options |
gr.Radio | String | Single selection from visible options |
gr.Image | NumPy array / PIL / filepath | Image upload, display, and editing |
gr.Audio | NumPy array / filepath | Audio recording, upload, and playback |
gr.Video | Filepath | Video upload and playback |
gr.File | Filepath | General file upload and download |
gr.Dataframe | Pandas DataFrame | Tabular data display and editing |
gr.Label | Dictionary | Classification label with confidence scores |
gr.HighlightedText | List of tuples | Text with color-coded spans |
gr.JSON | Dict / List | Structured JSON display |
gr.Code | String | Syntax-highlighted code editor |
gr.Chatbot | List of messages | Conversational message display |
gr.Plot | Matplotlib / Plotly figure | Chart and graph display |
gr.Gallery | List of images | Image grid display |
gr.Model3D | Filepath | 3D model viewer |
gr.LinePlot | DataFrame | Line chart display |
When using gr.Image as input, the function receives a NumPy array with shape (height, width, 3) representing RGB values. When using gr.Audio as input, the function receives a tuple of (sample_rate, audio_data). These conventions make it straightforward to connect Gradio components to standard ML libraries like PyTorch and TensorFlow.
One of Gradio's most distinctive features is the ability to create temporary public URLs for any app. Setting share=True in the launch() method generates a URL like https://07ff8706ab.gradio.live that tunnels to the local server using Fast Reverse Proxy (FRP). These share links expire after one week, but the processing happens entirely on the local machine, so no data is stored on Gradio's relay servers. This feature is particularly useful for sharing demos with collaborators or stakeholders who do not have a local Python environment.
For permanent hosting, Gradio apps can be deployed to Hugging Face Spaces, cloud platforms, or any server that supports Python.
By default, Gradio interfaces require the user to click a Submit button to trigger the function. Setting live=True enables continuous mode, where data is sent to the backend and the function reruns automatically whenever the input changes. This removes the Submit button and creates a reactive experience similar to Streamlit.
Gradio supports both input streaming and output streaming. For input streaming, the gr.Image and gr.Audio components can continuously capture data from a user's camera or microphone via the .stream() event. The stream_every parameter controls the capture frequency in seconds, and time_limit prevents a single user from occupying the processing queue indefinitely.
For output streaming, developers can set streaming=True on gr.Audio or gr.Video output components and write Python generators that yield successive chunks of media. Gradio 5 introduced low-latency streaming with automatic base64 encoding and WebSocket optimization, as well as WebRTC support through custom components. The related FastRTC library, also from the Gradio team, enables real-time audio and video communication over WebRTC or WebSockets.
Flagging is a built-in mechanism for collecting user feedback. When a user sees an input-output pair that appears incorrect or noteworthy, they can click the Flag button to save that data point. The input, output, and any flag label are logged to a CSV file in a flagged directory on the server. If the demo involves images, audio, or video, those files are saved separately with paths recorded in the CSV.
Gradio supports three flagging modes:
| Mode | Behavior |
|---|---|
"manual" | Users see a Flag button and click it to flag specific examples |
"auto" | Every interaction is automatically logged without a visible button |
"never" | No flagging button is shown and no data is collected |
Developers can also add custom flag labels (such as "Flag as Incorrect" and "Flag as Ambiguous") so that users can categorize their feedback.
The examples parameter on gr.Interface and within gr.Blocks allows developers to provide pre-filled input examples that users can click to quickly test the app. Examples can be cached so that the corresponding outputs are pre-computed, reducing wait times for common queries.
Gradio supports basic authentication through the auth parameter in launch(), which accepts a list of username-password tuples or a custom authentication function. This feature restricts access to the app without requiring external authentication infrastructure.
Hugging Face Spaces is the most popular platform for hosting Gradio apps. Spaces are Git repositories that automatically build and deploy whenever files are pushed. To deploy a Gradio app, developers create a Space at huggingface.co, select Gradio as the SDK, and push an app.py file along with a requirements.txt for dependencies.
Alternatively, the gradio deploy CLI command automates this process: it gathers metadata, uploads files (respecting .gitignore), and launches the app on Spaces. The platform supports incremental and collaborative development through standard Git workflows.
Hugging Face Spaces provides free CPU-based hosting with no credit card required. For compute-intensive applications, paid GPU options range from NVIDIA T4 instances at $0.40/hour to high-end configurations for demanding workloads. ZeroGPU, a dynamic GPU allocation feature, allows Spaces to use GPU resources only when processing requests, reducing costs for apps with sporadic traffic.
Gradio also integrates directly with the Hugging Face Hub's Serverless Inference Endpoints. Developers can create a demo by simply specifying a model name, and Gradio handles the API calls behind the scenes. Existing Gradio demos on Spaces can be remixed and combined to create new applications.
The Gradio Client libraries allow programmatic access to any Gradio app as an API. Available in both Python (gradio_client) and JavaScript (@gradio/client), these libraries turn any Gradio app into a callable service.
The Python client is included as a dependency when installing Gradio, or it can be installed separately as the lightweight gradio_client package (requires Python 3.10 or higher). Basic usage involves connecting to a Gradio app and calling its endpoints:
from gradio_client import Client
client = Client("abidlabs/whisper")
result = client.predict("audio_sample.wav")
The client provides two primary methods for invoking endpoints:
| Method | Behavior |
|---|---|
predict() | Blocking call that waits for the final result |
submit() | Non-blocking call that returns a Job object for async monitoring and streaming |
The view_api() method displays all available endpoints for a connected app, including parameter types and descriptions. The client works with any hosted Gradio app regardless of where it is deployed, not just apps on Hugging Face Spaces.
The @gradio/client npm package provides equivalent functionality for JavaScript and TypeScript environments, enabling integration with web applications and Node.js services.
Starting in 2025, Gradio added support for the Model Context Protocol (MCP), allowing any Gradio app to function as a tool server for AI agents and LLM applications. Enabling this feature requires a single parameter:
demo.launch(mcp_server=True)
Alternatively, developers can set the environment variable GRADIO_MCP_SERVER=True. Once enabled, the MCP endpoint is accessible at http://your-server:port/gradio_api/mcp/.
Gradio's MCP integration automatically converts Python functions into MCP tools by extracting function names as tool identifiers, parsing docstrings for descriptions, and using type hints for parameter schemas. The system supports HTTP-based connections for remote MCP clients, STDIO protocol for local connections, and Streamable HTTP for progress notifications.
Compatible MCP clients include Claude Desktop, Cursor, Cline, and any LLM application that supports the MCP protocol. Advanced features include authentication via gr.Header(), progress tracking with gr.Progress(), resource exposure with @gr.mcp.resource(), and reusable prompt templates with @gr.mcp.prompt().
Because Gradio apps can be hosted for free on Hugging Face Spaces, any developer can set up a free hosted MCP server without managing infrastructure.
Gradio supports the creation of custom components for cases where the built-in components do not meet specific requirements. The custom component workflow consists of three steps:
gradio cc create to generate a component template with Python and JavaScript scaffolding.gradio cc dev to launch a development server with hot reloading for rapid iteration.gradio cc build to package the component as a Python package that can be published to PyPI.Starting with Gradio 6, custom web components can be written inline in pure HTML and JavaScript directly within Python code, eliminating the need for external build tools or frameworks. Finished components can be shared through the Gradio Custom Components Gallery, where the community can browse, test, and copy code for contributed components.
Released on October 31, 2023, Gradio 4.0 was a major release that introduced several significant features:
Released on October 9, 2024, Gradio 5.0 focused on performance, design, and real-time capabilities:
Gradio 6.0, released in November 2025, delivered performance improvements, a smaller package footprint, and simplified customization:
gr.ChatInterface history format to OpenAI-style structured contentapi_visibility parameter replacing the previous api_name=False patterngr.Dataframe with new row_limits and column_limits parametersgr.LogoutButton and gradio sketch CLIAs of March 2026, the latest stable release is Gradio 6.x.
Gradio and Streamlit are the two most popular Python frameworks for building interactive ML and data applications. While they share a similar goal of making it easy to create web apps without front-end expertise, they differ in philosophy and strengths.
| Feature | Gradio | Streamlit |
|---|---|---|
| Primary focus | ML model demos and inference | Data apps, dashboards, and analytics |
| API style | Function-wrapping (Interface, Blocks) | Script-based (top-to-bottom execution) |
| Built-in ML components | Rich set: gr.Image, gr.Audio, gr.Video, gr.Model3D | Fewer ML-specific components; relies on third-party packages |
| Sharing | One-line share links (share=True) | Requires deployment to Streamlit Community Cloud or other host |
| Hosting platform | Hugging Face Spaces (free tier available) | Streamlit Community Cloud (free tier available) |
| Update model | Submit button by default; optional live=True for reactive mode | Reactive by default; reruns entire script on input change |
| Chatbot support | Built-in gr.ChatInterface with streaming and tool display | Requires manual implementation with st.chat_message |
| API access | Automatic API for every app; Python and JS clients | No built-in API client |
| MCP server support | Built-in (mcp_server=True) | Not natively supported |
| Custom components | Supported with gradio cc CLI workflow | Supported via st.components |
| Layout flexibility | Blocks API with Row, Column, Tab, Accordion | Columns, tabs, sidebar, expander |
| License | Apache 2.0 | Apache 2.0 |
| Community size | 42,000+ GitHub stars | 40,000+ GitHub stars |
In general, Gradio is the stronger choice when the goal is to quickly demo an ML model, share it with non-technical users, or expose it as an API. Streamlit is better suited for building full-featured data dashboards, analytics tools, or applications that require more UI customization and complex state management.
The most common use case for Gradio is building interactive demos for ML models. Researchers and engineers use Gradio to let others test image classification, object detection, text generation, speech recognition, and other models without writing any code. The AUTOMATIC1111 Stable Diffusion Web UI, one of the most popular interfaces for Stable Diffusion image generation, is built entirely on Gradio.
Teams use Gradio to build internal tools for tasks like data labeling, model evaluation, and quality assurance. The flagging feature makes it easy to collect feedback from domain experts who may not be familiar with Python or ML workflows.
Instructors and course creators use Gradio to build interactive exercises and demonstrations for ML courses. Hugging Face's own courses and tutorials frequently use Gradio for hands-on examples. The library's simplicity allows students to focus on model logic rather than web development.
With the Gradio Client and automatic API generation, developers use Gradio as a lightweight backend for ML inference services. Every Gradio app automatically exposes an API that can be accessed programmatically, making it useful for microservice architectures and integration with other applications.
With MCP server support, Gradio apps can serve as tools for AI agents. Any function exposed through a Gradio interface can be called by LLM-based agents running in compatible clients, enabling workflows where AI systems interact with custom tools built by developers.
Gradio has built a large and active community since its open-source release. As of early 2026, the library has over 42,000 GitHub stars, more than 13 million monthly PyPI downloads, and is used in over 500,000 Hugging Face Spaces. The project is maintained by a team at Hugging Face with contributions from the open-source community.
The ecosystem includes several related projects and resources:
The Gradio team has also organized community events, including the Agents and MCP Hackathon in 2025, which brought together developers building agentic applications with Gradio and the Model Context Protocol.
Gradio is released under the Apache 2.0 license, making it completely free to use, modify, and distribute for both personal and commercial purposes. There is no paid tier or premium version of the Gradio library itself.
For hosting, there are several free and paid options:
| Option | Cost | Details |
|---|---|---|
| Local development | Free | Run on any machine with Python installed |
| Temporary share links | Free | Public URL via share=True, expires after one week |
| Hugging Face Spaces (CPU) | Free | Permanent hosting with basic CPU compute |
| Hugging Face Spaces (GPU) | $0.40-$40+/hour | GPU-accelerated hosting with NVIDIA T4 through H200 |
| Self-hosted | Varies | Deploy to any cloud provider or on-premises server |
The combination of a permissive open-source license and free hosting through Hugging Face Spaces makes Gradio accessible to individual researchers, students, and organizations of all sizes.