🎉 We are joining Hugging Face! Read our announcement here. 🤗

If you are just getting started with Gradio, see the Getting Started guide.

Docs

Creating Interfaces

gradio.Interface(self, fn, inputs=None, outputs=None, examples=None, examples_per_page=10, live=False, layout="unaligned", interpretation=None, num_shap=2.0, theme=None, title=None, description=None, article=None, thumbnail=None, css=None, allow_screenshot=True, allow_flagging=None, flagging_options=None, flagging_dir="flagged")

Gradio interfaces are created by constructing a `Interface` object with a locally-defined function, or with `Interface.load()` with the path to a repo or by `Interface.from_pipeline()` with a Transformers Pipeline.

Parameters

  • fn (Union[Callable, List[Callable]]) - the function to wrap an interface around.
  • inputs (Union[str, InputComponent, List[Union[str, InputComponent]]]) - a single Gradio input component, or list of Gradio input components. Components can either be passed as instantiated objects, or referred to by their string shortcuts. The number of input components should match the number of parameters in fn.
  • outputs (Union[str, OutputComponent, List[Union[str, OutputComponent]]]) - a single Gradio output component, or list of Gradio output components. Components can either be passed as instantiated objects, or referred to by their string shortcuts. The number of output components should match the number of values returned by fn.
  • examples (Union[List[List[Any]], str]) - sample inputs for the function; if provided, appears below the UI components and can be used to populate the interface. Should be nested list, in which the outer list consists of samples and each inner list consists of an input corresponding to each input component. A string path to a directory of examples can also be provided. If there are multiple input components and a directory is provided, a log.csv file must be present in the directory to link corresponding inputs.
  • examples_per_page (int) - If examples are provided, how many to display per page.
  • live (bool) - whether the interface should automatically reload on change.
  • layout (str) - Layout of input and output panels. "horizontal" arranges them as two columns of equal height, "unaligned" arranges them as two columns of unequal height, and "vertical" arranges them vertically.
  • interpretation (Union[Callable, str]) - function that provides interpretation explaining prediction output. Pass "default" to use simple built-in interpreter, "shap" to use a built-in shapley-based interpreter, or your own custom interpretation function.
  • num_shap (float) - a multiplier that determines how many examples are computed for shap-based interpretation. Increasing this value will increase shap runtime, but improve results. Only applies if interpretation is "shap".
  • title (str) - a title for the interface; if provided, appears above the input and output components.
  • description (str) - a description for the interface; if provided, appears above the input and output components.
  • article (str) - an expanded article explaining the interface; if provided, appears below the input and output components. Accepts Markdown and HTML content.
  • thumbnail (str) - path to image or src to use as display picture for models listed in gradio.app/hub
  • theme (str) - Theme to use - one of "default", "huggingface", "seafoam", "grass", "peach". Add "dark-" prefix, e.g. "dark-peach" for dark theme (or just "dark" for the default dark theme).
  • css (str) - custom css or path to custom css file to use with interface.
  • allow_screenshot (bool) - if False, users will not see a button to take a screenshot of the interface.
  • allow_flagging (str) - one of "never", "auto", or "manual". If "never" or "auto", users will not see a button to flag an input and output. If "manual", users will see a button to flag. If "auto", every prediction will be automatically flagged. If "manual", samples are flagged when the user clicks flag button. Can be set with environmental variable GRADIO_ALLOW_FLAGGING.
  • flagging_options (List[str]) - if provided, allows user to select from the list of options when flagging. Only applies if allow_flagging is "manual".
  • flagging_dir (str) - what to name the dir where flagged data is stored.
gradio.Interface().launch(self, inline=None, inbrowser=None, share=False, debug=False, auth=None, auth_message=None, private_endpoint=None, prevent_thread_lock=False, show_error=True, server_name=None, server_port=None, show_tips=False, enable_queue=False, height=500, width=900, encrypt=False, cache_examples=False)

Launches the webserver that serves the UI for the interface.

Parameters

  • inline (bool) - whether to display in the interface inline on python notebooks.
  • inbrowser (bool) - whether to automatically launch the interface in a new tab on the default browser.
  • share (bool) - whether to create a publicly shareable link from your computer for the interface.
  • debug (bool) - if True, and the interface was launched from Google Colab, prints the errors in the cell output.
  • auth (Callable, Union[Tuple[str, str], List[Tuple[str, str]]]) - If provided, username and password (or list of username-password tuples) required to access interface. Can also provide function that takes username and password and returns True if valid login.
  • auth_message (str) - If provided, HTML message provided on login page.
  • private_endpoint (str) - If provided, the public URL of the interface will be this endpoint (should generally be unchanged).
  • prevent_thread_lock (bool) - If True, the interface will block the main thread while the server is running.
  • show_error (bool) - If True, any errors in the interface will be printed in the browser console log
  • server_port (int) - will start gradio app on this port (if available). Can be set by environment variable GRADIO_SERVER_PORT.
  • server_name (str) - to make app accessible on local network, set this to "0.0.0.0". Can be set by environment variable GRADIO_SERVER_NAME.
  • show_tips (bool) - if True, will occasionally show tips about new Gradio features
  • enable_queue (bool) - if True, inference requests will be served through a queue instead of with parallel threads. Required for longer inference times (> 1min) to prevent timeout.
  • width (int) - The width in pixels of the
  • height (int) - The height in pixels of the
  • encrypt (bool) - If True, flagged data will be encrypted by key provided by creator at launch
  • cache_examples (bool) - If True, examples outputs will be processed and cached in a folder, and will be used if a user uses an example input.
gradio.Interface.load(name, src=None, api_key=None, alias=None)

Class method to construct an Interface from an external source repository, such as huggingface.

Parameters

  • name (str) - the name of the model (e.g. "gpt2"), can include the `src` as prefix (e.g. "huggingface/gpt2")
  • src (str) - the source of the model: `huggingface` or `gradio` (or empty if source is provided as a prefix in `name`)
  • api_key (str) - optional api key for use with Hugging Face Model Hub
  • alias (str) - optional, used as the name of the loaded model instead of the default name

Returns

  • (gradio.Interface) - a Gradio Interface object for the given model

Input Components

gradio.inputs.Textbox(self, lines=1, placeholder=None, default="", label=None)

Component creates a textbox for user to enter input. Provides a string as an argument to the wrapped function.

Input type: str

Parameters

  • lines (int) - number of line rows to provide in textarea.
  • placeholder (str) - placeholder hint to provide behind textarea.
  • default (str) - default text to provide in textarea.
  • label (str) - component name in interface.

String Shortcuts

  • "text" - Uses defaults implementation.
  • "textbox" - Sets lines=7

Demos

hello_world: Open in Colab
diff_texts: Open in Colab
gradio.inputs.Number(self, default=None, label=None)

Component creates a field for user to enter numeric input. Provides a number as an argument to the wrapped function.

Input type: float

Parameters

  • default (float) - default value.
  • label (str) - component name in interface.

String Shortcuts

  • "number" - Uses defaults implementation.

Demos

tax_calculator: Open in Colab
titanic_survival: Open in Colab
gradio.inputs.Slider(self, minimum=0, maximum=100, step=None, default=None, label=None)

Component creates a slider that ranges from `minimum` to `maximum`. Provides a number as an argument to the wrapped function.

Input type: float

Parameters

  • minimum (float) - minimum value for slider.
  • maximum (float) - maximum value for slider.
  • step (float) - increment between slider values.
  • default (float) - default value.
  • label (str) - component name in interface.

String Shortcuts

  • "slider" - Uses defaults implementation.

Demos

sentence_builder: Open in Colab
generate_tone: Open in Colab
titanic_survival: Open in Colab
gradio.inputs.Checkbox(self, default=False, label=None)

Component creates a checkbox that can be set to `True` or `False`. Provides a boolean as an argument to the wrapped function.

Input type: bool

Parameters

  • label (str) - component name in interface.
  • default (bool) - default value.

String Shortcuts

  • "checkbox" - Uses defaults implementation.

Demos

sentence_builder: Open in Colab
titanic_survival: Open in Colab
gradio.inputs.CheckboxGroup(self, choices, default=[], type="value", label=None)

Component creates a set of checkboxes of which a subset can be selected. Provides a list of strings representing the selected choices as an argument to the wrapped function.

Input type: Union[List[str], List[int]]

Parameters

  • choices (List[str]) - list of options to select from.
  • default (List[str]) - default selected list of options.
  • type (str) - Type of value to be returned by component. "value" returns the list of strings of the choices selected, "index" returns the list of indicies of the choices selected.
  • label (str) - component name in interface.

Demos

sentence_builder: Open in Colab
titanic_survival: Open in Colab
fraud_detector: Open in Colab
gradio.inputs.Radio(self, choices, type="value", default=None, label=None)

Component creates a set of radio buttons of which only one can be selected. Provides string representing selected choice as an argument to the wrapped function.

Input type: Union[str, int]

Parameters

  • choices (List[str]) - list of options to select from.
  • type (str) - Type of value to be returned by component. "value" returns the string of the choice selected, "index" returns the index of the choice selected.
  • default (str) - default value.
  • label (str) - component name in interface.

Demos

sentence_builder: Open in Colab
tax_calculator: Open in Colab
titanic_survival: Open in Colab
gradio.inputs.Dropdown(self, choices, type="value", default=None, label=None)

Component creates a dropdown of which only one can be selected. Provides string representing selected choice as an argument to the wrapped function.

Input type: Union[str, int]

Parameters

  • choices (List[str]) - list of options to select from.
  • type (str) - Type of value to be returned by component. "value" returns the string of the choice selected, "index" returns the index of the choice selected.
  • default (str) - default value.
  • label (str) - component name in interface.

Demos

sentence_builder: Open in Colab
filter_records: Open in Colab
titanic_survival: Open in Colab
gradio.inputs.Image(self, shape=None, image_mode="RGB", invert_colors=False, source="upload", tool="editor", type="numpy", label=None, optional=False)

Component creates an image upload box with editing capabilities.

Input type: Union[numpy.array, PIL.Image, file-object]

Parameters

  • shape (Tuple[int, int]) - (width, height) shape to crop and resize image to; if None, matches input image size.
  • image_mode (str) - "RGB" if color, or "L" if black and white.
  • invert_colors (bool) - whether to invert the image as a preprocessing step.
  • source (str) - Source of image. "upload" creates a box where user can drop an image file, "webcam" allows user to take snapshot from their webcam, "canvas" defaults to a white image that can be edited and drawn upon with tools.
  • tool (str) - Tools used for editing. "editor" allows a full screen editor, "select" provides a cropping and zoom tool.
  • type (str) - Type of value to be returned by component. "numpy" returns a numpy array with shape (width, height, 3) and values from 0 to 255, "pil" returns a PIL image object, "file" returns a temporary file object whose path can be retrieved by file_obj.name, "filepath" returns the path directly.
  • label (str) - component name in interface.
  • optional (bool) - If True, the interface can be submitted with no uploaded image, in which case the input value is None.

String Shortcuts

  • "image" - Uses defaults implementation.
  • "webcam" - Sets source=webcam
  • "sketchpad" - Sets image_mode=L, source=canvas, shape=(28, 28), invert_colors=True

Demos

image_classifier: Open in Colab
image_mod: Open in Colab
webcam: Open in Colab
digit_classifier: Open in Colab
gradio.inputs.Video(self, type=None, source="upload", label=None, optional=False)

Component creates a video file upload that is converted to a file path.

Input type: filepath

Parameters

  • type (str) - Type of video format to be returned by component, such as 'avi' or 'mp4'. If set to None, video will keep uploaded format.
  • source (str) - Source of video. "upload" creates a box where user can drop an video file, "webcam" allows user to record a video from their webcam.
  • label (str) - component name in interface.
  • optional (bool) - If True, the interface can be submitted with no uploaded video, in which case the input value is None.

String Shortcuts

  • "video" - Uses defaults implementation.

Demos

video_flip: Open in Colab
gradio.inputs.Audio(self, source="upload", type="numpy", label=None, optional=False)

Component accepts audio input files.

Input type: Union[Tuple[int, numpy.array], file-object, numpy.array]

Parameters

  • source (str) - Source of audio. "upload" creates a box where user can drop an audio file, "microphone" creates a microphone input.
  • type (str) - Type of value to be returned by component. "numpy" returns a 2-set tuple with an integer sample_rate and the data numpy.array of shape (samples, 2), "file" returns a temporary file object whose path can be retrieved by file_obj.name, "filepath" returns the path directly.
  • label (str) - component name in interface.
  • optional (bool) - If True, the interface can be submitted with no uploaded audio, in which case the input value is None.

String Shortcuts

  • "audio" - Uses defaults implementation.
  • "microphone" - Sets source=microphone
  • "mic" - Sets source=microphone

Demos

main_note: Open in Colab
reverse_audio: Open in Colab
spectogram: Open in Colab
gradio.inputs.File(self, file_count="single", type="file", label=None, optional=False)

Component accepts generic file uploads.

Input type: Union[file-object, bytes, List[Union[file-object, bytes]]]

Parameters

  • file_count (str) - if single, allows user to upload one file. If "multiple", user uploads multiple files. If "directory", user uploads all files in selected directory. Return type will be list for each file in case of "multiple" or "directory".
  • type (str) - Type of value to be returned by component. "file" returns a temporary file object whose path can be retrieved by file_obj.name, "binary" returns an bytes object.
  • label (str) - component name in interface.
  • optional (bool) - If True, the interface can be submitted with no uploaded image, in which case the input value is None.

String Shortcuts

  • "file" - Uses defaults implementation.
  • "files" - Sets file_count=multiple

Demos

zip_to_json: Open in Colab
zip_two_files: Open in Colab
gradio.inputs.Dataframe(self, headers=None, row_count=3, col_count=3, datatype="str", col_width=None, default=None, type="pandas", label=None)

Component accepts 2D input through a spreadsheet interface.

Input type: Union[pandas.DataFrame, numpy.array, List[Union[str, float]], List[List[Union[str, float]]]]

Parameters

  • headers (List[str]) - Header names to dataframe.
  • row_count (int) - Limit number of rows for input.
  • col_count (int) - Limit number of columns for input. If equal to 1, return data will be one-dimensional. Ignored if `headers` is provided.
  • datatype (Union[str, List[str]]) - Datatype of values in sheet. Can be provided per column as a list of strings, or for the entire sheet as a single string. Valid datatypes are "str", "number", "bool", and "date".
  • col_width (Union[int, List[int]]) - Width of columns in pixels. Can be provided as single value or list of values per column.
  • default (List[List[Any]]) - Default value
  • type (str) - Type of value to be returned by component. "pandas" for pandas dataframe, "numpy" for numpy array, or "array" for a Python array.
  • label (str) - component name in interface.

String Shortcuts

  • "dataframe" - Sets type=pandas
  • "numpy" - Sets type=numpy
  • "matrix" - Sets type=array
  • "list" - Sets type=array, col_count=1

Demos

filter_records: Open in Colab
matrix_transpose: Open in Colab
tax_calculator: Open in Colab
gradio.inputs.Timeseries(self, x=None, y=None, label=None, optional=False)

Component accepts pandas.DataFrame uploaded as a timeseries csv file.

Input type: pandas.DataFrame

Parameters

  • x (str) - Column name of x (time) series. None if csv has no headers, in which case first column is x series.
  • y (Union[str, List[str]]) - Column name of y series, or list of column names if multiple series. None if csv has no headers, in which case every column after first is a y series.
  • label (str) - component name in interface.
  • optional (bool) - If True, the interface can be submitted with no uploaded csv file, in which case the input value is None.

String Shortcuts

  • "timeseries" - Uses defaults implementation.

Demos

fraud_detector: Open in Colab

Output Components

gradio.outputs.Textbox(self, type="auto", label=None)

Component creates a textbox to render output text or number.

Output type: Union[str, float, int]

Parameters

  • type (str) - Type of value to be passed to component. "str" expects a string, "number" expects a float value, "auto" detects return type.
  • label (str) - component name in interface.

String Shortcuts

  • "text" - Sets type=str
  • "textbox" - Sets type=str
  • "number" - Sets type=number

Demos

hello_world: Open in Colab
sentence_builder: Open in Colab
gradio.outputs.Label(self, num_top_classes=None, type="auto", label=None)

Component outputs a classification label, along with confidence scores of top categories if provided. Confidence scores are represented as a dictionary mapping labels to scores between 0 and 1.

Output type: Union[Dict[str, float], str, int, float]

Parameters

  • num_top_classes (int) - number of most confident classes to show.
  • type (str) - Type of value to be passed to component. "value" expects a single out label, "confidences" expects a dictionary mapping labels to confidence scores, "auto" detects return type.
  • label (str) - component name in interface.

String Shortcuts

  • "label" - Uses defaults implementation.

Demos

image_classifier: Open in Colab
main_note: Open in Colab
titanic_survival: Open in Colab
gradio.outputs.Image(self, type="auto", label=None)

Component displays an output image.

Output type: Union[numpy.array, PIL.Image, str, matplotlib.pyplot, Tuple[Union[numpy.array, PIL.Image, str], List[Tuple[str, float, float, float, float]]]]

Parameters

  • type (str) - Type of value to be passed to component. "numpy" expects a numpy array with shape (width, height, 3), "pil" expects a PIL image object, "file" expects a file path to the saved image or a remote URL, "plot" expects a matplotlib.pyplot object, "auto" detects return type.
  • label (str) - component name in interface.

String Shortcuts

  • "image" - Uses defaults implementation.
  • "plot" - Sets type=plot
  • "pil" - Sets type=pil

Demos

image_mod: Open in Colab
webcam: Open in Colab
gradio.outputs.Video(self, type=None, label=None)

Used for video output.

Output type: filepath

Parameters

  • type (str) - Type of video format to be passed to component, such as 'avi' or 'mp4'. Use 'mp4' to ensure browser playability. If set to None, video will keep returned format.
  • label (str) - component name in interface.

String Shortcuts

  • "video" - Uses defaults implementation.
  • "playable_video" - Sets type=mp4

Demos

video_flip: Open in Colab
gradio.outputs.KeyValues(self, label=None)

Component displays a table representing values for multiple fields.

Output type: Union[Dict, List[Tuple[str, Union[str, int, float]]]]

Parameters

  • label (str) - component name in interface.

String Shortcuts

  • "key_values" - Uses defaults implementation.

Demos

text_analysis: Open in Colab
gradio.outputs.HighlightedText(self, color_map=None, label=None, show_legend=False)

Component creates text that contains spans that are highlighted by category or numerical value. Output is represent as a list of Tuple pairs, where the first element represents the span of text represented by the tuple, and the second element represents the category or value of the text.

Output type: List[Tuple[str, Union[float, str]]]

Parameters

  • color_map (Dict[str, str]) - Map between category and respective colors
  • label (str) - component name in interface.
  • show_legend (bool) - whether to show span categories in a separate legend or inline.

String Shortcuts

  • "highlight" - Uses defaults implementation.

Demos

diff_texts: Open in Colab
text_analysis: Open in Colab
gradio.outputs.Audio(self, type="auto", label=None)

Creates an audio player that plays the output audio.

Output type: Union[Tuple[int, numpy.array], str]

Parameters

  • type (str) - Type of value to be passed to component. "numpy" returns a 2-set tuple with an integer sample_rate and the data numpy.array of shape (samples, 2), "file" returns a temporary file path to the saved wav audio file, "auto" detects return type.
  • label (str) - component name in interface.

String Shortcuts

  • "audio" - Uses defaults implementation.

Demos

generate_tone: Open in Colab
reverse_audio: Open in Colab
gradio.outputs.JSON(self, label=None)

Used for JSON output. Expects a JSON string or a Python object that is JSON serializable.

Output type: Union[str, Any]

Parameters

  • label (str) - component name in interface.

String Shortcuts

  • "json" - Uses defaults implementation.

Demos

zip_to_json: Open in Colab
gradio.outputs.HTML(self, label=None)

Used for HTML output. Expects an HTML valid string.

Output type: str

Parameters

  • label (str) - component name in interface.

String Shortcuts

  • "html" - Uses defaults implementation.

Demos

text_analysis: Open in Colab
gradio.outputs.File(self, label=None)

Used for file output.

Output type: Union[file-like, str]

Parameters

  • label (str) - component name in interface.

String Shortcuts

  • "file" - Uses defaults implementation.

Demos

zip_two_files: Open in Colab
gradio.outputs.Dataframe(self, headers=None, max_rows=20, max_cols=None, overflow_row_behaviour="paginate", type="auto", label=None)

Component displays 2D output through a spreadsheet interface.

Output type: Union[pandas.DataFrame, numpy.array, List[Union[str, float]], List[List[Union[str, float]]]]

Parameters

  • headers (List[str]) - Header names to dataframe. Only applicable if type is "numpy" or "array".
  • max_rows (int) - Maximum number of rows to display at once. Set to None for infinite.
  • max_cols (int) - Maximum number of columns to display at once. Set to None for infinite.
  • overflow_row_behaviour (str) - If set to "paginate", will create pages for overflow rows. If set to "show_ends", will show initial and final rows and truncate middle rows.
  • type (str) - Type of value to be passed to component. "pandas" for pandas dataframe, "numpy" for numpy array, or "array" for Python array, "auto" detects return type.
  • label (str) - component name in interface.

String Shortcuts

  • "dataframe" - Uses defaults implementation.
  • "numpy" - Sets type=numpy
  • "matrix" - Sets type=array
  • "list" - Sets type=array

Demos

filter_records: Open in Colab
matrix_transpose: Open in Colab
fraud_detector: Open in Colab
gradio.outputs.Timeseries(self, x=None, y=None, label=None)

Component accepts pandas.DataFrame.

Output type: pandas.DataFrame

Parameters

  • x (str) - Column name of x (time) series. None if csv has no headers, in which case first column is x series.
  • y (Union[str, List[str]]) - Column name of y series, or list of column names if multiple series. None if csv has no headers, in which case every column after first is a y series.
  • label (str) - component name in interface.

String Shortcuts

  • "timeseries" - Uses defaults implementation.

Demos

fraud_detector: Open in Colab