Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 37 ยท Getting Started

Install Gradio and Build Your First App

Install Gradio in a virtual environment, write a first Interface, run it, and learn what the page shows, which port it uses and how to fix common start-up errors.

Setting up Gradio takes one command and one file. In this lesson you create a clean environment, install the package, write a first app, run it, and learn to read what the browser shows. The commands and the app are real Gradio, so they are shown read-only. Two runnable stand-ins at the end let you practice the shape of an app inside your browser.

Requirements and installation

Gradio needs a recent Python 3 (check the release notes of your Gradio version for the exact minimum). Work in a virtual environment so the project has its own packages:

Terminal
python -m venv .venv
source .venv/bin/activate        # Windows PowerShell: .venv\Scripts\Activate.ps1
pip install --upgrade gradio
python -c "import gradio; print(gradio.__version__)"

The last command prints the installed version. Gradio changes between major versions (parameters move, defaults change), so when an example from the internet does not work, compare the version first. This track targets the current major line, and it points out places where older code differs.

Install Gradio with pip, not sudo pip. A virtual environment keeps your system Python clean and makes it easy to delete and recreate the setup.

The first app

Save this as app.py:

Python
import gradio as gr

def shout(text):
    return text.upper() + "!"

demo = gr.Interface(
    fn=shout,
    inputs="text",
    outputs="text",
    title="Shout",
    description="Type something and see it in capital letters.",
)

if __name__ == "__main__":
    demo.launch()

Run it:

Terminal
python app.py

The terminal prints a line such as * Running on local URL: http://127.0.0.1:7860. Open that address. The page shows the title Shout, the description, a text box labelled text, a Clear and a Submit button, and an output box. Typing hello and pressing Submit (or pressing Enter in the box) shows HELLO!.

What each part does

  • fn is the function Gradio calls. It receives the input values as arguments.
  • inputs="text" is a shortcut string for gr.Textbox(). Strings are convenient, but the component class lets you set labels and options, so most real apps use classes.
  • outputs="text" shows the return value in a read-only textbox.
  • title and description appear above the form. The description accepts Markdown.
  • launch() starts a local web server and blocks until you stop it with Ctrl+C.
  • The if __name__ == "__main__": guard keeps the server from starting if another file imports demo.

Using real components

Replace the shortcut strings with component objects to add labels, placeholder text and defaults:

Python
import gradio as gr

def shout(text, times):
    return (text.upper() + "! ") * int(times)

demo = gr.Interface(
    fn=shout,
    inputs=[
        gr.Textbox(label="Message", placeholder="Say something", lines=2),
        gr.Slider(1, 5, value=2, step=1, label="Repeat"),
    ],
    outputs=gr.Textbox(label="Result"),
)
demo.launch()

The page now shows a two-line text box named Message, a slider from 1 to 5 named Repeat that starts at 2, and an output box named Result. The order of the components matches the order of the function parameters, which is the most important rule of Interface. If you swap the two inputs in the list, the function receives the values swapped, and int(times) fails with a ValueError for text input.

Reading start-up problems

Symptom Likely cause Fix
ModuleNotFoundError: gradio Wrong Python or no virtual environment active Activate .venv, run pip install gradio again
OSError: Cannot find empty port Port range is busy Close other apps, or pass server_port= to launch()
Page does not open from another computer Server only listens on localhost Use server_name="0.0.0.0" (and mind your firewall)
An old copy keeps showing Browser cache or an old process still running Stop the old process, hard-refresh
Error badge after Submit Exception in your function Read the terminal traceback

Errors inside your function appear in two places: the terminal prints the full traceback, and the page shows a small red Error notice on the output. Always debug from the terminal.

Stand-in 1: the smallest possible "Interface"

This stand-in (our own code, not Gradio) models the contract: an app is a function plus input and output descriptions, and the framework calls the function with the values in order.

Python Stand-in: a tiny Interface class

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The mismatch check shows why the count of components must equal the count of function parameters.

Stand-in 2: order matters

Python Stand-in: swapped inputs

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

With swapped values the function raises AttributeError (an integer has no upper). Real Gradio would show the same traceback in the terminal.

A first-project checklist

  1. Create a folder and a virtual environment.
  2. pip install gradio.
  3. Put the function and the Interface in app.py.
  4. Run with python app.py and open the printed URL.
  5. Try the "Use via API" link at the bottom of the page to see the endpoint (see how Gradio works).
  6. Stop with Ctrl+C.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command installs Gradio?

    Gradio is a Python package on PyPI, so pip installs it. Use a virtual environment.
  2. 2. In gr.Interface, how are components matched to the function?

    Order is what matters. Labels are for people, not for matching.
  3. 3. What does launch() do by default?

    It starts a local server and blocks until you stop it. Sharing and deployment are separate options.
  4. 4. Where should you look first when the page shows an Error notice after Submit?

    The exception happened in your Python function, and the full traceback is printed in the terminal.

Summary

  • Install in a virtual environment with pip install gradio and check gradio.__version__.
  • A first app is a function, an Interface and launch().
  • Components are matched to parameters by position; use classes for labels and options.
  • The server runs on http://127.0.0.1:7860 by default.
  • Debug exceptions from the terminal traceback.

Next: How Gradio Works Under the Hood