Working with examples

Learn how to provide example inputs for your Gradio demos to help users understand your models

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

Single input

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

cache_examples=True

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.

Lazy caching

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.

Cache mode configuration

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