Gradio

Gradio is an open-source Python library that lets developers build interactive web interfaces for machine learning models, APIs, and arbitrary Python functions in a few lines of code. Created in 2019 by Abubakar Abid during his PhD at Stanford University and acquired by Hugging Face in December 2021, Gradio has become one of the most widely used tools for building and sharing ML demos: it is released under the permissive Apache 2.0 license, is used by more than 1 million developers each month, and has accumulated over 42,000 stars on GitHub. ^[1][2][3] At the time of the Hugging Face acquisition, more than 300,000 demos had already been built with the library. ^[2] The original 2019 research paper framed the goal plainly: "Gradio makes accessing any ML model as easy as sharing a URL." ^[1]

History

What problem was Gradio built to solve?

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. ^[7]

The founding paper, "Gradio: Hassle-Free Sharing and Testing of ML Models in the Wild" (arXiv:1906.02569, published June 6, 2019), describes this same gap: "Typical ML models are built by specialists and require specialized hardware/software as well as ML experience to validate. This makes it challenging for non-technical collaborators and endpoint users (e.g. physicians) to easily provide feedback on model development." ^[1] 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.

Accelerator and early growth (2019-2021)

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 (a coauthor on the original paper) as an academic advisor, and the cofounders brought experience from organizations like Tesla and Google. ^[1][7]

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. ^[7] This pivot proved decisive: the library's simplicity and usefulness attracted a rapidly growing community of ML practitioners.

When did Hugging Face acquire Gradio?

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. ^[2]

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. The acquisition announcement summarized the combined goal: "By working together with Hugging Face, we're taking this even further so that machine learning is accessible to literally anyone with an internet connection and a browser." ^[2] 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.

Core Concepts

Gradio is organized around three main abstractions that accommodate different levels of complexity: Interface, ChatInterface, and Blocks. ^[4]

Interface

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:

Scroll sideways for more →

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. ^[4]

ChatInterface

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. ^[4]

Blocks

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:

Scroll sideways for more →

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. ^[4]

Components

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. ^[4]

Input and Output Components

Scroll sideways for more →

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. ^[4]

Key Features

How do Gradio share links work?

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. ^[4] 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.

Live Mode

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. ^[4]

Streaming

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. ^[3] The related FastRTC library, also from the Gradio team, enables real-time audio and video communication over WebRTC or WebSockets.

Flagging

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. ^[4]

Gradio supports three flagging modes:

Scroll sideways for more →

Developers can also add custom flag labels (such as "Flag as Incorrect" and "Flag as Ambiguous") so that users can categorize their feedback.

Examples

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. ^[4]

Authentication

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. ^[4]

Integration with Hugging Face Spaces

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. ^[4]

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.

Gradio Client

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. ^[4]

Python Client

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:

Scroll sideways for more →

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. ^[4]

JavaScript Client

The @gradio/client npm package provides equivalent functionality for JavaScript and TypeScript environments, enabling integration with web applications and Node.js services.

Gradio as an MCP Server

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: ^[6]

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/. ^[6]

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. ^[10]

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(). ^[6]

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.

Custom Components

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: ^[4]

1. Create: Run gradio cc create to generate a component template with Python and JavaScript scaffolding.
2. Dev: Run gradio cc dev to launch a development server with hot reloading for rapid iteration.
3. Build: Run 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. ^[8] Finished components can be shared through the Gradio Custom Components Gallery, where the community can browse, test, and copy code for contributed components.

Version History

Gradio has shipped several major versions, each on roughly an annual cadence. As of June 2026, the latest stable release is Gradio 6.19.0, published on June 17, 2026. ^[9]

Scroll sideways for more →

Gradio 4.0 (October 2023)

Released on October 31, 2023, Gradio 4.0 was a major release that introduced several significant features:

• Custom components framework for building bespoke interface elements
• Server-side events for improved front-end and back-end communication
• Improved media components with video trimming and waveform views for audio
• Accessibility improvements including keyboard navigation and better HTML semantics for screen readers
• Support for custom share servers, allowing apps to be hosted on a user's own domain

Gradio 5.0 (October 2024)

Released on October 9, 2024, Gradio 5.0 focused on performance, design, and real-time capabilities: ^[3]

• Server-side rendering (SSR) for near-instantaneous app loading in the browser
• Refreshed design for core components including Buttons, Tabs, and Sliders
• Low-latency streaming with automatic base64 encoding and WebSocket optimization
• WebRTC support via custom components for real-time audio and video
• Experimental AI Playground at gradio.app/playground for generating and modifying Gradio apps using AI
• Third-party security audit and enhanced web security practices
• New built-in themes for modern-looking apps

Gradio 6.0 (November 2025)

Gradio 6.0, released in November 2025, delivered performance improvements, a smaller package footprint, and simplified customization: ^[8]

• Inline custom web components in pure HTML and JavaScript within Python, with no build tools required
• Standardized Python API with several breaking changes for consistency
• Updated gr.ChatInterface history format to OpenAI-style structured content
• New api_visibility parameter replacing the previous api_name=False pattern
• Restructured gr.Dataframe with new row_limits and column_limits parameters
• Removal of deprecated features including gr.LogoutButton and gradio sketch CLI
• Following this release, only Gradio 6 receives ongoing support

How does Gradio compare with Streamlit?

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.

Scroll sideways for more →

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.

What is Gradio used for?

Model Demos and Prototyping

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. Hugging Face describes Gradio as the backbone of "some of the most popular open-source projects of all time," including AUTOMATIC1111, Oobabooga's Text Generation WebUI, DALL-E Mini, and LLaMA-Factory. ^[3] The AUTOMATIC1111 Stable Diffusion Web UI, one of the most popular interfaces for Stable Diffusion image generation, is built entirely on Gradio.

Internal Tools

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.

Education

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.

API Services

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.

AI Agent Tooling

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. ^[6]

Community and Ecosystem

Gradio has built a large and active community since its open-source release. As of mid-2026, the library has over 42,000 GitHub stars and more than 12 million monthly downloads on PyPI, and Hugging Face reports that Gradio is used by more than 1 million developers each month. ^[3][5][9] 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:

• Gradio Custom Components Gallery: A community-maintained collection of reusable components
• FastRTC: A companion library from the Gradio team for real-time audio and video communication
• Gradio Lite: A version of Gradio that runs entirely in the browser using Pyodide, with no server required
• Awesome Gradio Demos: A curated repository of example applications
• Hugging Face Courses: Multiple courses and tutorials that use Gradio for interactive examples

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.

Is Gradio free? Pricing and Licensing

Gradio is released under the Apache 2.0 license, making it completely free to use, modify, and distribute for both personal and commercial purposes. ^[5] There is no paid tier or premium version of the Gradio library itself.

For hosting, there are several free and paid options:

Scroll sideways for more →

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.

References

1. Abid, A., Abdalla, A., Abid, A., Khan, D., Alfozan, A., & Zou, J. (2019). "Gradio: Hassle-Free Sharing and Testing of ML Models in the Wild." arXiv preprint arXiv:1906.02569. https://arxiv.org/abs/1906.02569 ↩
2. "Gradio is joining Hugging Face!" Hugging Face Blog, December 21, 2021. https://huggingface.co/blog/gradio-joins-hf ↩
3. "Journey to 1 Million Gradio Users!" Hugging Face Blog, April 4, 2025. https://huggingface.co/blog/gradio-1m ↩
4. Gradio Official Documentation. https://www.gradio.app/docs ↩
5. Gradio GitHub Repository. https://github.com/gradio-app/gradio ↩
6. "Building MCP Server with Gradio." Gradio Guides. https://www.gradio.app/guides/building-mcp-server-with-gradio ↩
7. "Looking back at PearX S19 alum Gradio's journey, now part of Hugging Face." Pear VC. https://pear.vc/looking-back-at-pearx-s19-alum-gradios-journey-now-part-of-hugging-face/ ↩
8. "Gradio 6 Migration Guide." Gradio Documentation. https://www.gradio.app/main/guides/gradio-6-migration-guide ↩
9. Gradio PyPI Page. https://pypi.org/project/gradio/ ↩
10. "How to Build an MCP Server with Gradio." Hugging Face Blog. https://huggingface.co/blog/gradio-mcp ↩