Gradio

6.10.0 verified Tue May 12 auth: no python install: reviewed quickstart: stale

Python library for building ML demo web apps. Current version is 6.10.0 (Mar 2026). Requires Python >=3.10. Three major breaking version bumps in rapid succession (3→4→5→6). The most common LLM footgun: gr.update() was removed in 4.0 — return component instances directly. Chatbot tuple format removed in 6.0 — must use messages dict format. LLMs trained before 2024 generate 3.x patterns that fail on 6.x.

pip install gradio

Common errors

error AttributeError: type object 'Component' has no attribute 'update' ↓

cause The `gr.update()` method and `component.update()` methods were removed in Gradio 4.0. Components are now updated by directly returning a new instance of the component with the desired changes.

fix

Instead of calling .update(), return a new instance of the component from your function with the desired properties. For example, gr.Textbox(value='New text') instead of gr.Textbox().update(value='New text').

error UserWarning: The 'tuples' format for chatbot messages is deprecated and will be removed in a future version of Gradio. Please set type='messages' instead, which uses openai-style 'role' and 'content' keys. ↓

cause Gradio 6.0 removed the tuple format for `gr.Chatbot` and `gr.ChatInterface` history and examples. The new format requires a list of dictionaries, each containing 'role' and 'content' keys, aligning with OpenAI's message format.

fix

Migrate your chatbot history and examples to the messages format. Each message should be a dictionary like {'role': 'user', 'content': 'Hello'} or {'role': 'assistant', 'content': 'Hi there!'}. For gr.Chatbot you can also explicitly set type='messages' if it's not the default.

error ModuleNotFoundError: No module named 'gradio' ↓

cause The Gradio library is not installed in the currently active Python environment, or there is a conflict with multiple Python installations/virtual environments.

fix

Ensure Gradio is installed in your active Python environment by running pip install gradio. If using virtual environments, activate the correct one before installing or running your script. If multiple Python installations exist, ensure you're using the correct python executable.

error gradio.exceptions.Error: Data incompatible with messages format. Each message should be a dictionary with 'role' and 'content' keys or a ChatMessage object. ↓

cause This error occurs in Gradio 6.x when a `gr.Chatbot` or `gr.ChatInterface` is configured for the 'messages' format (which is now the default) but receives chat history or new messages in the older tuple format `[user_message, assistant_message]`.

fix

Ensure all chat history and new messages returned by your function are in the dictionary format [{'role': 'user', 'content': '...'}] or ChatMessage objects, not tuples.

error AttributeError: partially initialized module 'gradio' has no attribute 'Interface' (most likely due to a circular import) ↓

cause This typically happens when your Python script file is named `gradio.py`. Python tries to import your file instead of the actual Gradio library, leading to a circular import and this `AttributeError`.

fix

Rename your Python script file to something other than gradio.py (e.g., app.py, my_gradio_app.py).

Warnings

breaking gr.update() was removed in Gradio 4.0. The entire pattern of returning gr.Textbox.update(value='x') or gr.update(visible=True) raises AttributeError. This is the #1 footgun from LLM-generated code using old Gradio docs. ↓

fix Return a component instance directly: return gr.Textbox(value='text', visible=True). For multiple outputs, return a tuple: return gr.Textbox(value='text'), gr.Button(visible=False)

breaking Chatbot tuple format ([['user', 'assistant'], ...]) removed in Gradio 6.0. gr.Chatbot() and gr.ChatInterface() now require dict messages format: [{'role': 'user', 'content': '...'}, {'role': 'assistant', 'content': '...'}] ↓

fix Use type='messages' in gr.Chatbot(type='messages'). Format history as: [{'role': 'user', 'content': msg}, {'role': 'assistant', 'content': response}]

breaking theme= parameter removed from gr.Blocks() in Gradio 6.0. TypeError: BlockContext.__init__() got an unexpected keyword argument 'theme'. Breaks all apps using gr.Blocks(theme=gr.themes.Soft()). ↓

fix Pass theme at the app level instead: demo = gr.Blocks(); demo.theme = gr.themes.Soft(). Or use theme in gr.Interface(theme=...).

breaking concurrency_count parameter removed in Gradio 4.0. Per-event concurrency_limit replaced it. queue=False also removed — use concurrency_limit=None instead. ↓

fix Replace: demo.queue(concurrency_count=5) with per-event: btn.click(fn, ..., concurrency_limit=5). For unlimited: concurrency_limit=None.

breaking In Gradio 5.0+, functions can only return files in the current working directory or temp directory. Returning absolute paths to arbitrary system files is blocked for security. ↓

fix Save output files to tempfile.NamedTemporaryFile() or the current working directory. Return the path from tempfile.

gotcha Python 3.10 is now the minimum. Running Gradio on Python 3.9 may lead to dependency conflicts, such as `ImportError: cannot import name 'HfFolder' from 'huggingface_hub'`, as newer Gradio versions and their dependencies are designed for Python 3.10+. ↓

fix Upgrade to Python 3.10+. Pin gradio<5.0 for Python 3.9 environments.

gotcha LLMs (including ChatGPT and Copilot) frequently generate Gradio 3.x code with gr.update() and tuple chatbot format that fails on 6.x. Always verify which Gradio version the generated code targets. ↓

fix When using AI to generate Gradio code, explicitly prompt: 'Use Gradio 6.x API — no gr.update(), use messages dict format for Chatbot.'

Install compatibility reviewed last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 11.85s 290.0M

3.10 slim (glibc) - - 8.02s 284M

3.11 alpine (musl) - - 15.61s 312.2M

3.11 slim (glibc) - - 13.12s 305M

3.12 alpine (musl) - - 7.78s 295.9M

3.12 slim (glibc) - - 7.62s 289M

3.13 alpine (musl) - - 7.28s 295.2M

3.13 slim (glibc) - - 7.47s 288M

3.9 alpine (musl) - - - -

3.9 slim (glibc) - - - -

Imports

gr.Interface

wrong

# gr.update() removed in 4.0 — AttributeError in 4.x+:
def update_textbox(text):
    return gr.update(value=text, visible=True)  # AttributeError

# Also wrong — old tuple chatbot format removed in 6.0:
chatbot = gr.Chatbot(value=[['Hello', 'Hi there!']])  # breaks in 6.0

correct

import gradio as gr

# Simple Interface (gr.update() is gone — return values directly)
def greet(name, intensity):
    return 'Hello, ' + name + '!' * intensity

demo = gr.Interface(
    fn=greet,
    inputs=[gr.Textbox(label='Name'), gr.Slider(1, 10, value=3)],
    outputs=gr.Textbox(label='Greeting')
)
demo.launch()

gr.update() was removed in Gradio 4.0. Return component instances directly: return gr.Textbox(value='text', visible=True). Chatbot messages must use dict format in 6.0+: [{'role': 'user', 'content': 'Hello'}]

Quickstart stale last tested: 2026-04-23

6.x API. Use type='messages' for gr.Chatbot. Return component instances, not gr.update().

import gradio as gr

# Simple Interface
def classify_text(text):
    return {'positive': 0.8, 'negative': 0.2}

gr.Interface(
    fn=classify_text,
    inputs=gr.Textbox(label='Input Text'),
    outputs=gr.Label(label='Sentiment')
).launch()


# Blocks API (more flexible)
def chat(message, history):
    # history is list of dicts: [{role, content}, ...]
    response = f'Echo: {message}'
    return response

with gr.Blocks() as demo:
    gr.Markdown('# My Chatbot')
    chatbot = gr.Chatbot(type='messages')  # dict format required in 6.0
    msg = gr.Textbox(label='Message')
    btn = gr.Button('Send')
    
    def respond(message, history):
        history.append({'role': 'user', 'content': message})
        history.append({'role': 'assistant', 'content': f'Echo: {message}'})
        return '', history
    
    btn.click(respond, [msg, chatbot], [msg, chatbot])

demo.launch(share=True)