# Gradio

> Source: https://aiwiki.ai/wiki/gradio
> Updated: 2026-06-24
> Categories: Developer Tools, Machine Learning, Open Source AI, Programming Languages
> From AI Wiki (https://aiwiki.ai), a free encyclopedia of artificial intelligence. Quote with attribution.

Gradio is an open-source [Python](/wiki/python) library that lets developers build interactive web interfaces for [machine learning](/wiki/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](/wiki/stanford_university) and acquired by [Hugging Face](/wiki/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](/wiki/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](/wiki/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](/wiki/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:

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

```python
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](/wiki/large_language_model), supporting streaming responses and tool usage display. For servers compatible with the [OpenAI](/wiki/openai) API (such as [Ollama](/wiki/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:

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

| 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](/wiki/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](/wiki/pytorch) and [TensorFlow](/wiki/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](/wiki/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:

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

### 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](/wiki/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](/wiki/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:

```python
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. [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](/wiki/model_context_protocol) (MCP), allowing any Gradio app to function as a tool server for [AI agents](/wiki/ai_agents) and LLM applications. Enabling this feature requires a single parameter: [6]

```python
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](/wiki/claude) Desktop, [Cursor](/wiki/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]

| Major version | Release date | Headline focus |
|---------------|-------------|----------------|
| Gradio 4.0 | October 31, 2023 | Custom components framework, server-side events |
| Gradio 5.0 | October 9, 2024 | Server-side rendering, real-time streaming, AI Playground |
| Gradio 6.0 | November 2025 | Inline web components, smaller footprint, API cleanup |

### 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](/wiki/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.

## 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](/wiki/image_classification_models), [object detection](/wiki/object_detection), [text generation](/wiki/text_generation_models), [speech recognition](/wiki/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](/wiki/automatic1111) Stable Diffusion Web UI, one of the most popular interfaces for [Stable Diffusion](/wiki/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:

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

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