Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/gradio-app/gradio/llms.txt

Use this file to discover all available pages before exploring further.

Providing examples makes it easier for users to try your demo and understand the types of inputs your model expects. Examples appear below the UI components and can be clicked to populate the interface.

​
Basic usage

Add examples to an Interface by providing a list of lists to the examples keyword argument: 
import gradio as gr

def calculator(num1, operation, num2):
    if operation == "add":
        return num1 + num2
    elif operation == "subtract":
        return num1 - num2
    elif operation == "multiply":
        return num1 * num2
    elif operation == "divide":
        if num2 == 0:
            raise gr.Error("Cannot divide by zero!")
        return num1 / num2

demo = gr.Interface(
    calculator,
    [
        "number",
        gr.Radio(["add", "subtract", "multiply", "divide"]),
        "number"
    ],
    "number",
    examples=[
        [45, "add", 3],
        [3.14, "divide", 2],
        [144, "multiply", 2.5],
        [0, "subtract", 1.2],
    ],
    title="Toy Calculator",
    description="Here's a sample toy calculator."
)

demo.launch()

​
Example format

Each sublist within the outer list represents a data sample, and each element within the sublist represents an input for each input component:
  • The inputs must be ordered in the same order as the prediction function expects them
  • Each element corresponds to one input component
  • If your interface only has one input component, you can provide examples as a regular list instead of a list of lists
# For a single input, you can use a simple list
examples=["Hello", "Good morning", "Hi there"]

​
Loading from a directory

You can specify a path to a directory containing your examples:
1

Single file-type input

If your Interface takes only a single file-type input (e.g., an image classifier), simply pass a directory filepath:
gr.Interface(
    fn=image_classifier,
    inputs="image",
    outputs="label",
    examples="/path/to/images/"
)
The Interface will load all images in the directory as examples.
2

Multiple inputs with log.csv

For multiple inputs, the directory must contain a log.csv file with example values:
num,operation,num2
5,"add",3
4,"divide",2
5,"multiply",3
Then reference the directory:
gr.Interface(
    fn=calculator,
    inputs=[...],
    outputs=[...],
    examples="/demo/calculator/examples"
)
3

Loading flagged data

This approach is helpful when browsing flagged data. Simply point to the flagged directory:
examples="./flagged"

​
Partial examples

Sometimes your app has many input components, but you only want to provide examples for a subset of them. Pass None for data samples corresponding to components you want to exclude: 
import gradio as gr

def generate_image(prompt, negative_prompt, seed, steps):
    # Generation logic here
    pass

demo = gr.Interface(
    generate_image,
    inputs=[
        gr.Textbox(label="Prompt"),
        gr.Textbox(label="Negative Prompt"),
        gr.Number(label="Seed"),
        gr.Slider(1, 100, label="Steps")
    ],
    outputs="image",
    examples=[
        ["A sunset over mountains", None, None, None],
        ["A cat in space", "blurry, low quality", 42, None],
        ["Abstract art", None, 123, 50],
    ]
)

demo.launch()

​
Pagination

Examples are automatically paginated when you have many of them. Control the number per page: 
gr.Interface(
    fn=model,
    inputs=[...],
    outputs=[...],
    examples=large_dataset,
    examples_per_page=10  # Default is 10
)
This is useful for browsing and interacting with large datasets through Gradio.

​
Caching examples

You may want to cache example outputs so users can quickly try them without waiting for your model to run.
When set to True, your Gradio app runs all examples and saves outputs when you call launch():
demo = gr.Interface(
    fn=slow_model,
    inputs=[...],
    outputs=[...],
    examples=[[...]],
    cache_examples=True
)

demo.launch()  # Examples are cached during launch
The cache is saved in a gradio_cached_examples directory by default. Set the GRADIO_EXAMPLES_CACHE environment variable to use a custom directory path.
With lazy caching, each example is cached only after first use by any user:
demo = gr.Interface(
    fn=slow_model,
    inputs=[...],
    outputs=[...],
    examples=[[...]],
    cache_examples="lazy"
)

demo.launch()  # App starts immediately
This is helpful if your prediction function is long-running and you don’t want to wait during app startup.
Control when caching happens with cache_mode:
demo = gr.Interface(
    fn=model,
    inputs=[...],
    outputs=[...],
    examples=[[...]],
    cache_examples=True,
    cache_mode="eager"  # or "lazy"
)
  • "eager" - All examples cached at app launch (default)
  • "lazy" - Examples cached after first use
On HuggingFace Spaces, eager mode is default except for ZeroGPU Spaces which use lazy mode.
Once the cache is generated, it won’t update automatically in future launches. If examples or function logic change, delete the cache folder to rebuild it.Cached examples don’t support certain features like gr.Progress(), gr.Info(), or gr.Warning() in the UI.

​
Example labels

Instead of rendering example values, you can provide custom labels: 
gr.Interface(
    fn=model,
    inputs="image",
    outputs="label",
    examples=[
        ["image1.jpg"],
        ["image2.jpg"],
        ["image3.jpg"],
    ],
    example_labels=[
        "Mountain landscape",
        "City skyline",
        "Ocean sunset"
    ]
)
The length of example_labels should match the number of examples.

​
Preloading examples

You can preload a specific example when the app first loads: 
gr.Interface(
    fn=model,
    inputs=[...],
    outputs=[...],
    examples=[[...]],
    cache_examples=True,
    preload_example=0  # Preload the first example (0-indexed)
)
Preloading only works when:
  • Examples are cached eagerly (cache_examples=True and cache_mode="eager")
  • None of the input components have a developer-provided value
Set to False to disable preloading: 
preload_example=False

​
Examples with state

Cache examples cannot be used with state inputs and outputs. Gradio automatically sets cache_examples=False when state components are detected.

​
Next steps

Interface class

Learn more about the Interface class

Flagging

Allow users to flag interesting outputs

Build docs developers (and LLMs) love

Get started for freeTalk to us