如何使用 Python 的 Gradio：从入门到进阶完整教程

Gradio is one of those Python libraries that makes you wonder why building a web interface ever had to be complicated in the first place. You've probably experienced this before: you write a Python program, and it works. Your machine learning model produces predictions. Your AI application gives surprisingly good answers. Your data processing script does exactly what you wanted. Then someone else wants to use it. You send them the Python file. They ask how to run it. You explain that they need Python. Then they need the right Python version. Then they need the dependencies. Then they need to run pip install. Then something doesn't work. And suddenly, the application you were excited to share has become a troubleshooting session. This is one of the problems Gradio helps solve. Gradio lets you take Python functions, machine learning models, data-processing workflows, and AI applications and put an interactive web interface around them without requiring you to build the frontend from scratch. You can create text boxes, buttons, image uploaders, audio inputs, chat interfaces, file uploaders, data tables, dropdowns, sliders, and much more, all from Python. And you don't have to become a JavaScript developer before you can build something people can interact with. This book will take you from your first Gradio application to building and deploying complete AI-powered applications. By the end, you won't just know how to use individual Gradio components. You'll understand how Gradio applications are structured, how events connect the interface to Python functions, how state works, how to handle files and media, how to connect applications to machine learning models and AI APIs, and how to share your applications with other people. What We'll Cover: 1. What is Gradio and Why Does It Exist? 2. Installing Gradio and Setting Up Your Environment 3. Your First Gradio App 4. Understanding the Gradio Mental Model 5. Inputs and Outputs 6. Gradio Components 7. Buttons, Events, and Interactivity 8. Working with Multiple Inputs and Outputs 9. Layouts, Rows, Columns, Tabs, and Blocks 10. State and Managing Data Between Interactions 11. File Uploads and File Processing 12. Images, Audio, Video, and Other Media 13. Chatbots andgr.ChatInterface 14. Customizing the User Interface 15. Connecting Gradio to Machine Learning Models 16. Building an AI Text Generator 17. Building an Image Classification App 18. Building an AI Chatbot 19. Building a File Analysis AI Agent 20. Sharing Gradio Apps 21. Deploying Gradio Apps to Hugging Face Spaces 22. Environment Variables, Secrets, and API Keys 23. Performance, Errors, Security, and Production Tips 24. Build a Complete AI-Powered Gradio Application 25. Where to Go After Gradio Final Perspective Let's get started. 1. What is Gradio and Why Does It Exist? The Problem Gradio Solves Imagine that you've trained a machine learning model that determines whether an image contains a cat or a dog. Your Python code might look something like this: def predict(image): # Run the image through a trained model prediction = model(image) return prediction From a developer's perspective, this might be enough. But from a user's perspective, it isn't. A regular user doesn't want to open a Python file and figure out how to call predict(). They want something more like this: Open a webpage. Upload an image. Click a button. See the prediction. Traditionally, creating that experience could require several different technologies. You might need Python for the backend, HTML and CSS for the interface, JavaScript for browser interactions, and some mechanism for connecting the frontend to the Python backend. That isn't necessarily bad. Those technologies are incredibly useful. But sometimes you don't need a complete custom web stack. Sometimes you already have the interesting part of the application written in Python. You just need a simple interface around it. That's where Gradio comes in. What Gradio is Gradio is a Python library for creating interactive web-based interfaces for Python functions and applications. The important idea is this: You provide the Python logic, and Gradio provides a way for users to interact with it. For example, suppose you have this function: def greet(name): return f"Hello, {name}!" You can turn that function into an interactive interface with Gradio. import gradio as gr def greet(name): return f"Hello, {name}!" demo = gr.Interface( fn=greet, inputs="text", outputs="text" ) demo.launch() When you run the program, Gradio starts a local web application. Instead of calling the function yourself from Python, a user can enter their name into a text field and interact with the function through the browser. That's the basic Gradio philosophy. Gradio isn't the Model This distinction is important: Gradio doesn't magically turn your application into an AI model. Gradio is the interface layer. Suppose you've built an image classifier. Your machine learning model is responsible for making the prediction. Your Python code is responsible for processing the input and calling the model. Gradio provides the interface through which someone can provide the input and see the result. This separation is useful because the underlying Python logic doesn't have to be an AI model. It could be almost anything. For example: def calculate_area(width, height): return width * height Or: def reverse_text(text): return text[::-1] Or: def analyze_sentiment(text): ... Or: def summarize_document(file): ... Or: def generate_response(message, history): ... Gradio can sit around all of these kinds of Python functionality. Why Gradio is Especially Popular for AI Applications Gradio became particularly useful in the machine learning and generative AI ecosystem because machine learning developers often work primarily in Python. A developer may already know how to: load a model, preprocess data, run inference, process the result, and return a prediction. What they may not want to do is spend several hours building a frontend for every experiment. Gradio makes it possible to turn an experiment into something interactive relatively quickly. This is especially useful for: machine learning demonstrations computer vision applications natural language processing generative AI applications chatbots audio applications document processing data analysis tools educational tools prototypes research demonstrations Gradio vs Building a Frontend from Scratch There are situations where you absolutely should build a custom frontend. If you're creating a large consumer application, a complex dashboard, or a highly customized product, a dedicated frontend framework may make more sense. But there is a major difference between: "I need a production-grade custom web application." and: "I have a Python model and want people to interact with it." Gradio is designed particularly well for the second situation. You can create a working interface with surprisingly little code. Your Python Function is the Starting Point One of the most useful ways to think about Gradio is to begin with the Python function. Suppose you have: def multiply(a, b): return a * b You can imagine the application as having three conceptual pieces: inputs Python logic outputs The user provides a and b. Your function receives them. The function returns a result. Gradio handles the interaction between the user and that function. This concept will appear repeatedly throughout this book. As the applications become more complicated, you'll introduce events, state, layouts, multiple components, files, models, APIs, and chat histories. But underneath all of that, the same basic idea remains: Something happens in the interface, Python processes it, and the result is sent back to the interface. What You Can Build with Gradio You can use Gradio for much more than simple demonstrations. For example, you could build a text summarizer: def summarize(text): # Your summarization logic goes here return summary A user could paste text into a textbox and receive a summary. You could build an image classifier: def classify_image(image): # Your model inference code goes here return prediction A user could upload an image and receive a prediction. You could build a sentiment analyzer: def analyze_sentiment(text): # Your NLP logic goes here return result Or a document analyzer: def analyze_document(file): # Extract and analyze the document return analysis Or a chatbot: def respond(message, history): # Your chatbot logic goes here return response The interface changes depending on the problem, but the underlying Python logic remains the heart of the application. What You'll Learn in This Book This book starts with the simplest possible applications and gradually introduces more advanced concepts. You'll learn how to: install Gradio create your first interface work with inputs and outputs use Gradio components respond to user events create complex layouts manage application state accept uploaded files work with images, audio, and video create chat interfaces customize your applications connect Gradio to machine learning models build AI applications work with APIs deploy applications protect API keys handle errors think about security and performance build a complete AI-powered application You don't need to know JavaScript to follow the core examples in this book. You should, however, be comfortable with basic Python concepts such as functions, variables, strings, lists, dictionaries, imports, and conditional statements. If you know more Python than that, even better. A Quick Look at the Gradio Workflow A typical Gradio application begins with Python code. You define a function. def greet(name): return f"Hello, {name}!" You create an interface. import gradio as gr demo = gr.Interface( fn=greet, inputs="text", outputs="text" ) Then you launch it. demo.launch() That's enough to create a basic interactive application. Of course, real applications can become much more sophisticated. But learning Gradio doesn't require you to understand everything at once. We'll build the knowledge one layer at a time. Why Learning Gradio is Useful Gradio is particularly valuable if you're interested in Python, data science, machine learning, or AI. It gives you a way to bridge the gap between: "I wrote a Python program." and: "Someone else can actually use my Python program." That distinction matters. A model sitting inside a notebook is useful for experimentation. But a model wrapped in an accessible interface can become a demonstration, a classroom project, a research prototype, an internal tool, or the starting point for a larger application. Gradio doesn't eliminate the need to understand software development. Instead, it gives Python developers a convenient way to turn their existing logic into interactive applications. And that's exactly what we're going to learn how to do. 2. Installing Gradio and Setting Up Your Environment Before building applications, we need to set up a Python environment. This section will keep the setup straightforward because the goal isn't to spend an hour configuring your computer before you've written a single line of Gradio code. Check Your Python Installation Open your terminal or command prompt. On many systems, you can check Python with: python --version Depending on your operating system, you may instead need: python3 --version You should see a Python version printed in the terminal. For example: Python 3.x.x The exact version you see will depend on your installation. If Python isn't installed, install a current supported Python version from the official Python distribution for your operating system. Why Virtual Environments Are Useful You could install Gradio globally on your computer. But using a virtual environment is generally a better habit for Python projects. A virtual environment gives your project its own isolated collection of Python packages. Imagine that one project requires one version of a library while another project requires a different version. Installing everything globally can eventually create dependency conflicts. With a virtual environment, your Gradio project can keep its dependencies separate. Create a Project Directory Create a folder for your project. For example: gradio-course Then move into that folder: cd gradio-course The exact command depends on where you created the directory. Create a Virtual Environment You can create a virtual environment with Python's built-in venv module: python -m venv .venv On systems where python3 is the command used to run Python: python3 -m venv .venv The .venv folder contains the environment. You generally don't need to edit anything inside it manually. Activate the Environment on Windows On Windows, activation commonly looks like: .venv\Scripts\activate After activation, your terminal should indicate that the virtual environment is active. Activate the Environment on macOS or Linux On macOS and Linux, use: source .venv/bin/activate Again, your terminal will usually show that the environment is active. Install Gradio Once your environment is active, install Gradio with: pip install gradio Python's package installer will download Gradio and its dependencies. When the installation completes, you can verify that Gradio is available. One simple way is to open Python: python Then: import gradio print(gradio.__version__) If the import succeeds, Gradio is installed. Exit Python with: exit() Create Your First Project File Create a file called: app.py This will be the main Python file for our first application. Your project might now look roughly like this: gradio-course/ .venv/ app.py You don't need to manually create .venv if you used the virtual environment command. Python created it for you. Your First Import Open app.py and write: import gradio as gr The as gr portion creates a shorter name for the package. Instead of writing: gradio.Interface(...) we can write: gr.Interface(...) You'll see gr used throughout Gradio documentation and examples. A Common Installation Problem If your terminal says something similar to: 'python' is not recognized or: command not found: python the problem isn't necessarily Gradio. Your system may not have Python installed correctly, or Python may not be available through your command line. Likewise, if: pip install gradio doesn't work, you can often use: python -m pip install gradio This explicitly tells Python to run its package installer. On some systems: python3 -m pip install gradio may be appropriate. Why python -m pip Can Be Useful Suppose you have multiple Python installations. You run: pip install gradio but the pip command might be associated with a different Python installation than the one you use to run your program. Using: python -m pip install gradio ties the package installation to the Python interpreter represented by python. That can prevent a surprisingly annoying class of dependency problems. Running Your Gradio Application Once app.py contains an application, you'll run it from the terminal. For example: python app.py Gradio will start a local server. You'll generally see information in your terminal telling you where the application is available. A local Gradio application commonly opens at an address on your own computer, such as: http://127.0.0.1:7860 The important word here is local. At this stage, you're running the application on your own machine. Other people on the internet aren't automatically accessing it. Local Development vs Deployment This distinction will become important later. When you run: python app.py you're developing locally. When you deploy your application to a service such as Hugging Face Spaces, the application can become accessible remotely depending on the configuration and visibility of the deployment. Don't worry about deployment yet. For now, local development is exactly what we want. Your Development Loop As you build Gradio applications, you'll repeatedly follow a simple development cycle: Write Python code. Run the application. Open the interface. Test it. Notice something that could be improved. Stop or reload the application as needed. Modify the code. Test again. This is normal software development. Don't expect your first version to be perfect. The goal of this book is to teach you how to understand what your code is doing so that when something goes wrong, you have a reasonable idea of where to look. 3. Your First Gradio App Now we're ready to build something. Not a huge AI application. Not a complicated dashboard. Just a small application that accepts a person's name and returns a greeting. This may seem almost too simple, but that's intentional. A small application lets us focus on how Gradio works without introducing unnecessary complexity. Create a Greeting Function Start with: def greet(name): return f"Hello, {name}!" This is ordinary Python. There's nothing Gradio-specific about it. If you run: print(greet("Eva")) you would get: Hello, Eva! That's important because the function itself doesn't know Gradio exists. It simply accepts an argument and returns a value. Import Gradio At the top of your file: import gradio as gr Your file now looks like: import gradio as gr def greet(name): return f"Hello, {name}!" Now we need to connect that function to a user interface. Create an Interface Add: demo = gr.Interface( fn=greet, inputs="text", outputs="text" ) The entire program is now: import gradio as gr def greet(name): return f"Hello, {name}!" demo = gr.Interface( fn=greet, inputs="text", outputs="text" ) demo.launch() Run it: python app.py You should now have a web interface that lets you provide text to the greet() function and see the returned text. Congratulations! You've built your first Gradio application. Understanding gr.Interface Let's slow down and examine the most important part: gr.Interface( fn=greet, inputs="text", outputs="text" ) Interface is a convenient way to create an interface around a function. It needs to know three particularly important things here: what function to call, what kind of input the function expects, and what kind of output the function returns. That's why we specify: fn=greet inputs="text" and: outputs="text" Understanding fn This: fn=greet means that greet is the function Gradio should call. Notice that we did not write: fn=greet() That's a subtle but important Python distinction. greet refers to the function itself, while greet() calls the function immediately. We want Gradio to control when the function gets called. So we provide the function: fn=greet rather than immediately executing it. Understanding the Input This: inputs="text" tells Gradio that the application should provide a text input. The user can type something into that input. Gradio then passes the resulting value to our Python function. If the user types: Maria Gradio effectively supplies that value to: greet(name) so the function receives: name = "Maria" and returns: Hello, Maria! Understanding the Output We specify: outputs="text" because our function returns a string. The returned value is displayed in a text output. This is why it's useful to think about the function's input and output types. Our function has: text → text It accepts text and returns text. Later we'll build functions that work with: number → number or: image → prediction or: file → analysis or: message + history → response The interface needs to match the function. Understanding launch() The final line is: demo.launch() This tells Gradio to start the application. Without it, you've created the interface object but haven't started the application server. Think of it as the instruction that says: "Okay, Gradio. Start this application so a user can interact with it." Add a Title We can make the application a little more descriptive. demo = gr.Interface( fn=greet, inputs="text", outputs="text", title="Greeting App" ) Now the interface has a title. Add a Description You can also provide a description: demo = gr.Interface( fn=greet, inputs="text", outputs="text", title="Greeting App", description="Enter your name and receive a personalized greeting." ) Descriptions are useful because users shouldn't have to guess what your application does. Give the Input a Label Instead of relying on a generic text input, you can use a component explicitly. name_input = gr.Textbox( label="Your Name", placeholder="Enter your name" ) Then: output = gr.Textbox( label="Greeting" ) Now we can pass those components to Interface: import gradio as gr def greet(name): return f"Hello, {name}!" name_input = gr.Textbox( label="Your Name", placeholder="Enter your name" ) output = gr.Textbox( label="Greeting" ) demo = gr.Interface( fn=greet, inputs=name_input, outputs=output, title="Greeting App", description="Enter your name and receive a personalized greeting." ) demo.launch() This version is more explicit. Instead of simply saying: inputs="text" we've created a Textbox component and configured it. That becomes useful as our applications become more sophisticated. What Happens When the User Clicks the Button? A basic Gradio interface generally gives the user an interaction mechanism such as a button. When the user provides input and triggers the interface: Gradio obtains the input. Gradio passes the input to your Python function. Your function executes. Your function returns a result. Gradio places that result into the output component. Your Python function doesn't need to know how the browser is rendering the input. That's Gradio's job. Functions Don't Have to Be Called predict You'll often see machine learning examples using: def predict(...): ... That's simply a naming convention. Your function can be called anything: def greet(...): ... def analyze(...): ... def generate(...): ... Gradio cares about the function you provide, not what you named it. Build a Calculator Let's create something slightly more interesting. import gradio as gr def add_numbers(a, b): return a + b demo = gr.Interface( fn=add_numbers, inputs=[ gr.Number(label="First Number"), gr.Number(label="Second Number") ], outputs=gr.Number(label="Result"), title="Addition Calculator" ) demo.launch() Notice something new: our function has two parameters: def add_numbers(a, b): Therefore, we provide two inputs: inputs=[ gr.Number(label="First Number"), gr.Number(label="Second Number") ] The order matters. The first input is passed to a. The second input is passed to b. Multiple Inputs Suppose the user enters 10 and 25... Gradio calls the function conceptually like: add_numbers(10, 25) The function returns: 35 and Gradio displays that result. This pattern becomes extremely important. If your Python function accepts multiple arguments, your Gradio interface needs corresponding inputs. A Simple Text Analyzer Let's build another application. import gradio as gr def analyze_text(text): characters = len(text) words = len(text.split()) return f"Characters: {characters}\nWords: {words}" demo = gr.Interface( fn=analyze_text, inputs=gr.Textbox( label="Enter Text", lines=8, placeholder="Type or paste some text here..." ), outputs=gr.Textbox( label="Analysis" ), title="Text Analyzer" ) demo.launch() This application demonstrates a useful pattern. The user provides text, Python processes it, and the interface displays the result. There's no AI model involved, as there doesn't need to be. Gradio is useful for ordinary Python applications, too. Why Start with Simple Applications? Because the same concepts scale. Consider the text analyzer. Today, it calculates word and character counts. Tomorrow, you could replace the function with a sentiment model: def analyze_text(text): return sentiment_model(text) Or a summarization model: def analyze_text(text): return summarization_model(text) Or an API call: def analyze_text(text): return call_ai_api(text) The interface could remain broadly similar. That's one of the strengths of separating the UI from the application logic. A Useful Mental Exercise Whenever you're building a Gradio application, ask yourself: What does my Python function need? For example: def greet(name): It needs one piece of text, so we need one text input. For: def add_numbers(a, b): we need two numeric inputs. For: def classify(image): we need an image input. For: def analyze(file): we need a file input. Thinking this way makes designing interfaces much easier. Common Beginner Mistake: Mismatched Inputs Suppose you write: def multiply(a, b): return a * b but create: demo = gr.Interface( fn=multiply, inputs=gr.Number(), outputs=gr.Number() ) You have only provided one input even though the function expects two arguments. Gradio can't magically know what the missing b should be. You need: demo = gr.Interface( fn=multiply, inputs=[ gr.Number(), gr.Number() ], outputs=gr.Number() ) This is one of the most important relationships to understand: Your interface inputs should match the parameters your function expects. Common Beginner Mistake: Returning the Wrong Thing Suppose your interface expects a number: outputs=gr.Number() but your function returns: return "This is a string" That mismatch can cause problems. The components aren't merely visual elements. They communicate what kind of data is expected. As you learn more components, you'll become better at designing these data flows. 4. Understanding the Gradio Mental Model Before learning dozens of components, it's worth spending time understanding how Gradio applications think. If you understand the underlying model, the syntax becomes much easier to learn. But if you only memorize syntax, Gradio can become confusing as soon as your application has multiple interactions. Gradio Connects Interfaces to Functions At its simplest, a Gradio application connects a user interface to Python logic. You might have: def square(number): return number ** 2 The interface provides the number, the function processes it., and the interface displays the result. That's the core pattern. Think in Terms of Inputs and Outputs When you encounter a new Gradio application, don't immediately try to understand every line. First ask: What goes into the application? Then: What happens to that input? Then: What comes out? For example: def uppercase(text): return text.upper() The input is text., the processing is converting it to uppercase, and the output is text. So the interface needs: inputs=gr.Textbox() and: outputs=gr.Textbox() Your Python Function is the Logic Layer Your function is where your application's behavior lives. For example: def calculate_discount(price, percentage): discount = price * (percentage / 100) return price - discount The function doesn't care whether the input came from Gradio. It could just as easily be called from another Python program: result = calculate_discount(100, 20) That's a useful design principle. Try to keep your Python logic understandable independently from your UI code. Your Components Are the Interface Layer Gradio components represent the controls users interact with. Examples include: gr.Textbox() gr.Number() gr.Slider() gr.Dropdown() gr.File() gr.Image() The component determines how the user provides or receives information. Events Connect Actions to Functions As applications become more complex, we won't always use the simple Interface pattern. Instead, we'll create individual components and connect them using events. For example: button.click( fn=greet, inputs=name, outputs=output ) Here, the button's click event tells Gradio: When this button is clicked, run the greet function using the value from name, then place the result into output. This is a more flexible way of thinking about Gradio. The Event-Driven Model Suppose you have: button = gr.Button("Analyze") and: text = gr.Textbox() and: result = gr.Textbox() You can connect them: button.click( fn=analyze, inputs=text, outputs=result ) Now the relationship is explicit. The button triggers the function, the textbox supplies the input, and the result textbox receives the output. This is the foundation of more complex Gradio applications. Interface vs Blocks You've already seen: gr.Interface(...) Later, you'll work extensively with: gr.Blocks() These aren't competing versions of the same thing. They're different approaches to building interfaces. Interface is convenient when your application follows a relatively straightforward function-input-output pattern. For example: demo = gr.Interface( fn=translate, inputs=gr.Textbox(), outputs=gr.Textbox() ) This is concise and useful. But suppose you want: multiple buttons several input components different sections tabs custom event behavior multiple outputs components that update other components application state Then Blocks gives you much more control. The Basic Blocks Structure A simple Blocks application looks like this: import gradio as gr def greet(name): return f"Hello, {name}!" with gr.Blocks() as demo: name = gr.Textbox(label="Name") button = gr.Button("Greet") output = gr.Textbox(label="Greeting") button.click( fn=greet, inputs=name, outputs=output ) demo.launch() There are several new ideas here. The with Statement This: with gr.Blocks() as demo: creates a Gradio application context. Components created inside that block become part of the interface. For example: name = gr.Textbox() creates a textbox in the application. Then: button = gr.Button("Greet") creates a button. And: output = gr.Textbox() creates an output textbox. Why Blocks Matters The biggest difference is control. With Interface, you describe a relatively straightforward function interface. With Blocks, you construct the application yourself. You decide: which components exist where they appear which events trigger which functions which components depend on which other components This makes Blocks especially useful for real applications. Components Can Be Stored in Variables Notice: name = gr.Textbox(label="Name") We store the component in a Python variable. That's important because we can later reference it. For example: button.click( fn=greet, inputs=name, outputs=output ) The variable name represents the component. Likewise, output represents the output component. This makes it possible to connect components together. An Event Doesn't Execute the Function Immediately Consider: button.click( fn=greet, inputs=name, outputs=output ) You might initially wonder: "When does greet() run?" It doesn't run simply because this line appears in your Python file. You're configuring the event and telling Gradio what should happen later. The function runs when the user performs the corresponding interaction. This distinction is fundamental. Your Python program first constructs the application, then the application waits for user interaction. When the user clicks the button, Gradio invokes the configured function. The Application Has Two Sides It can help to separate the application conceptually into construction time and interaction time. Your Python code creates components and event relationships. The user interacts with those components and triggers your functions. For example: with gr.Blocks() as demo: name = gr.Textbox() button = gr.Button() output = gr.Textbox() button.click( fn=greet, inputs=name, outputs=output ) During construction, Gradio learns about the textbox, button, output, and event. Later, when the user clicks the button, the function executes. Data Flows Through Your Application Suppose the user types: Alex into the name textbox. Then they click: Greet Gradio takes the value from the component: name and passes it into: greet The function produces: Hello, Alex! Gradio then places that value into: output This pattern will become more complicated later, but it doesn't fundamentally change. Why This Mental Model Makes Debugging Easier Suppose your button does nothing. Instead of randomly changing code, ask a sequence of questions. Is the button created? button = gr.Button("Greet") Is the event attached? button.click(...) Is the correct function provided? fn=greet Is the input component correct? inputs=name Is the output component correct? outputs=output Does the Python function itself work? print(greet("Alex")) This approach is much more effective than treating the entire application as one mysterious block. Keep Your Python Functions Simple A common beginner temptation is to put everything inside an event handler. For example: def process(text): # 100 lines of unrelated work ... That can make debugging difficult. Instead, as your application grows, consider separating responsibilities. For example: def clean_text(text): return text.strip() def analyze_text(text): cleaned = clean_text(text) return { "characters": len(cleaned), "words": len(cleaned.split()) } Then Gradio can call: def analyze_text(...) while the underlying Python code remains organized. Gradio Doesn't Replace Python This may sound obvious, but it's worth emphasizing. Gradio makes interfaces easier. It doesn't replace the need to understand the Python logic behind your application. If your application processes a PDF, you still need to know how to extract information from the PDF. If your application calls a machine learning model, you still need to understand how to use the model. If your application communicates with an API, you still need to understand the API. Gradio handles the interface and interaction layer. Your Python code handles the application logic. The Three Questions to Ask When Learning a New Gradio Feature Whenever you encounter a new feature, ask: What does the user interact with? That tells you which component or event is involved. What Python data does it produce? That tells you what your function receives. What does my function return? That tells you what the output component needs to display. For example, with an image classifier, the user interacts with an image uploader, the Python function receives image data, and the model produces a prediction. Gradio displays that prediction. From Simple Applications to AI Applications At this point, you already know enough to understand the basic architecture of a surprisingly large number of Gradio applications. A machine learning application might look conceptually like: def predict(image): processed_image = preprocess(image) prediction = model(processed_image) return prediction Gradio provides: gr.Image() as the input and a suitable output component for the prediction. An AI text application might look like: def generate(prompt): response = model.generate(prompt) return response Gradio provides a textbox for the prompt and another component for the response. A document analyzer might look like: def analyze(file): text = extract_text(file) result = analyze_text(text) return result Gradio provides the file upload interface and displays the result. The domain changes, the model changes, and the Python code changes. But the fundamental interaction pattern stays remarkably consistent. What You've Learned So Far You now have the conceptual foundation for the rest of the book. You know that Gradio: provides interfaces for Python applications, can wrap ordinary Python functions, is especially useful for machine learning and AI applications, separates interface concerns from application logic, supports many different input and output types, can create simple interfaces with Interface, can create more customizable applications with Blocks, uses events to connect user actions to Python functions, and passes data between components and functions. The next step is to go deeper into exactly how data enters and leaves a Gradio application. That means inputs and outputs. And once you understand those, the rest of the component system becomes much easier to learn. 5. Inputs and Outputs Now that you understand the basic Gradio mental model, it's time to look more closely at one of the most important parts of any Gradio application: inputs and outputs. A Gradio application is only useful if it can receive information from a user and return something useful. That sounds simple, but there are many different kinds of information a user might provide. They might type a sentence, upload an image, select an option from a dropdown, move a slider, upload a PDF, record audio, or provide several pieces of information at once. Gradio has components designed for all of these situations. What is an Input? An input is information that your application receives from the user. For example: name = gr.Textbox() The user can type a value into the textbox. That value can then be passed to a Python function. Consider: def greet(name): return f"Hello, {name}!" Here, name is the input. What is an Output? An output is information that your application gives back to the user. For example: output = gr.Textbox() Your Python function might return a string, which Gradio places into that component. The basic relationship looks like this in code: def greet(name): return f"Hello, {name}!" with gr.Blocks() as demo: name = gr.Textbox(label="Name") output = gr.Textbox(label="Greeting") button = gr.Button("Greet") button.click( fn=greet, inputs=name, outputs=output ) demo.launch() The textbox provides the input, the function processes it, and the second textbox displays the output. Inputs and Outputs Aren't Necessarily Different Component Types A common misconception is that some components are "input components" while others are "output components." In reality, many Gradio components can be used in either role. For example: gr.Textbox() can receive text or display text. Likewise: gr.Image() can be used to accept an image or display an image. The way a component is used depends on where you connect it. One Input and One Output Let's start with the simplest possible pattern. import gradio as gr def double(number): return number * 2 with gr.Blocks() as demo: number = gr.Number(label="Number") result = gr.Number(label="Result") button = gr.Button("Double") button.click( fn=double, inputs=number, outputs=result ) demo.launch() The user enters a number and the button triggers double(). Then the result is displayed. Multiple Inputs Python functions can accept multiple arguments. For example: def calculate_total(price, quantity): return price * quantity The function needs two inputs. We can provide two components: import gradio as gr def calculate_total(price, quantity): return price * quantity with gr.Blocks() as demo: price = gr.Number(label="Price") quantity = gr.Number(label="Quantity") result = gr.Number(label="Total") button = gr.Button("Calculate") button.click( fn=calculate_total, inputs=[price, quantity], outputs=result ) demo.launch() The list: inputs=[price, quantity] determines the order in which values are passed to the function. The first component supplies price. The second supplies quantity. Conceptually, Gradio performs the equivalent of: calculate_total(price_value, quantity_value) Multiple Outputs Functions can also return multiple values. Suppose we want to analyze a sentence: def analyze_text(text): characters = len(text) words = len(text.split()) return characters, words The function returns two values, so we provide two outputs: import gradio as gr def analyze_text(text): characters = len(text) words = len(text.split()) return characters, words with gr.Blocks() as demo: text = gr.Textbox( label="Text", lines=6 ) characters = gr.Number( label="Characters" ) words = gr.Number( label="Words" ) button = gr.Button("Analyze") button.click( fn=analyze_text, inputs=text, outputs=[characters, words] ) demo.launch() The first returned value goes to the first output. The second returned value goes to the second output. Output Ordering Matters Suppose: def analyze_text(text): return characters, words and: outputs=[characters_output, words_output] Everything matches. But if you accidentally write: outputs=[words_output, characters_output] the values will appear in the wrong places. This is why keeping your input and output ordering clear is important. Using Dictionaries For Structured Results Sometimes an application produces several related pieces of information. You could return a dictionary from Python: def analyze_person(name, age): return { "name": name, "age": age, "adult": age >= 18 } You could display the result using an appropriate component such as gr.JSON. import gradio as gr def analyze_person(name, age): return { "name": name, "age": age, "adult": age >= 18 } with gr.Blocks() as demo: name = gr.Textbox(label="Name") age = gr.Number(label="Age") output = gr.JSON(label="Result") button = gr.Button("Analyze") button.click( fn=analyze_person, inputs=[name, age], outputs=output ) demo.launch() This is useful when your function produces structured information. Input Components Can Have Default Values You can provide an initial value. For example: gr.Textbox( value="Hello!" ) Or: gr.Number( value=10 ) Or: gr.Slider( minimum=0, maximum=100, value=50 ) This can make applications easier to understand because users immediately see what kind of value the component expects. Labels Help Users Understand Your Interface Compare: gr.Textbox() with: gr.Textbox( label="Enter your question" ) The second version communicates much more clearly. Labels should describe the purpose of the component rather than simply repeating its data type. For example, this: gr.Textbox(label="Question") is generally more useful than: gr.Textbox(label="Textbox") Placeholder Text A placeholder can provide an example without actually filling the input. gr.Textbox( label="Question", placeholder="Ask something about your document..." ) A placeholder disappears once the user starts typing. That makes it useful for examples and hints. The Difference Between value and placeholder Consider: gr.Textbox( value="Hello" ) The textbox actually contains "Hello". Now: gr.Textbox( placeholder="Type something here..." ) The textbox is empty. The phrase is simply shown as a hint. This distinction matters when you're designing forms. Lines and Larger Text Areas For longer text, you can use: gr.Textbox( lines=10 ) This gives users more room to type. A text-generation application might use: prompt = gr.Textbox( label="Prompt", lines=8, placeholder="Describe what you want the AI to generate..." ) Making a Component Non-interactive Sometimes you want users to see information but not edit it. You can control whether a component is interactive. For example: output = gr.Textbox( label="Generated Result", interactive=False ) This is particularly useful for output components. Making a Component Invisible You can also control visibility. gr.Textbox( visible=False ) This can be useful when a component is only needed under certain conditions. Later, you'll learn how to dynamically change component properties based on events. Components Don't Have to Be Directly Connected to Buttons An interaction can also happen when the user changes a component. For example: name.change( fn=greet, inputs=name, outputs=output ) Now the function can run when the value changes rather than waiting for a button click. We'll explore events in much greater depth in Chapter 7. Understanding Data Types Different components naturally represent different kinds of information. A Textbox generally deals with strings. A Number deals with numerical values. An Image deals with image data. A Checkbox represents a Boolean value. A Dropdown returns the selected option. A Slider returns a numerical value. This matters because your Python function should expect the type of data the component provides. For example: def is_adult(age): return age >= 18 A Number makes sense here. Using a textbox would mean you'd need to convert the string to a number: def is_adult(age): age = int(age) return age >= 18 Choosing the appropriate component can reduce unnecessary data conversion. Converting Input Values Yourself Sometimes conversion is necessary. For example: def calculate_age_in_months(age): return int(age) * 12 If you're receiving text, you may need: age = int(age) But don't perform conversions blindly. Users can enter unexpected values. For example, this will fail: int("hello") Good applications validate inputs before processing them. Input Validation Suppose we have: def divide(a, b): return a / b What happens if b is zero? Python raises an error. A safer version is: def divide(a, b): if b == 0: return "You cannot divide by zero." return a / b The application can then return a useful message instead of crashing the interaction. As applications become more complex, validation becomes increasingly important. A Form with Several Inputs Let's build a small profile generator. import gradio as gr def create_profile(name, age, occupation): return ( f"Name: {name}\n" f"Age: {age}\n" f"Occupation: {occupation}" ) with gr.Blocks() as demo: name = gr.Textbox(label="Name") age = gr.Number(label="Age") occupation = gr.Textbox(label="Occupation") button = gr.Button("Create Profile") output = gr.Textbox( label="Profile" ) button.click( fn=create_profile, inputs=[name, age, occupation], outputs=output ) demo.launch() This demonstrates a pattern you'll use constantly: collect → process → display. Inputs Don't Have to Come from the Same Type of Component You can combine different component types. For example: def create_message(name, age, subscribed): status = "subscribed" if subscribed else "not subscribed" return f"{name} is {age} years old and is {status}." The interface could use: name = gr.Textbox() age = gr.Number() subscribed = gr.Checkbox() Then: button.click( fn=create_message, inputs=[name, age, subscribed], outputs=output ) Gradio passes the values in the appropriate order. Optional Inputs Your Python function can also define defaults. For example: def greet(name, greeting="Hello"): return f"{greeting}, {name}!" You need to think carefully about how optional parameters interact with the interface. In many applications, it's clearer to expose the options explicitly: greeting = gr.Dropdown( choices=["Hello", "Hi", "Welcome"] ) Then: button.click( fn=greet, inputs=[name, greeting], outputs=output ) This gives the user direct control. Inputs and Outputs as Application Contracts A useful way to think about components is as a contract. Your function says: "Give me these values, and I'll give you these results." Your Gradio interface says: "I'll collect those values from the user and display those results." When those two sides agree, your application works smoothly. When they don't, you'll encounter errors or confusing behavior. Try It Yourself Let's build a temperature converter. Your application should: accept a temperature in Celsius convert it to Fahrenheit display the result Start with this Python function: def celsius_to_fahrenheit(celsius): return (celsius * 9 / 5) + 32 Then create the Gradio interface yourself. Once that works, modify it so the user can choose between Celsius and Fahrenheit. Key Takeaways Inputs are values supplied to your Python functions. Outputs are values returned to the user. Functions can have multiple inputs. Functions can return multiple outputs. Input and output ordering matters. Component types should match the data your application expects. Labels and placeholders make interfaces easier to understand. Validation prevents invalid user input from causing failures. Components can be used as both inputs and outputs depending on how they're connected. 6. Gradio Components Gradio provides a large collection of components for building interactive interfaces. You don't need to memorize all of them. In fact, trying to memorize every component would be a poor use of your time. Instead, you should understand what the major components are designed to do and learn how to configure them. Once you understand the pattern, looking up a specific parameter later becomes much easier. Textbox The Textbox is one of the most frequently used components. text = gr.Textbox() It can accept text from a user or display text generated by your application. A more descriptive version might be: text = gr.Textbox( label="Your Question", placeholder="Ask a question...", lines=5 ) You can use textboxes for: names questions prompts descriptions paragraphs code generated responses summaries error messages Number Use gr.Number when your application expects numerical input. number = gr.Number( label="Enter a number" ) You can also specify a default value: number = gr.Number( label="Quantity", value=1 ) This is preferable to using a textbox when the value is fundamentally numerical. Slider A slider lets the user select a value within a range. temperature = gr.Slider( minimum=0, maximum=100, value=50, label="Temperature" ) Sliders are useful when the user is selecting from a continuous or bounded numerical range. For example: confidence thresholds percentages image brightness generation settings volume numerical parameters Slider Steps You can control how much the slider changes at a time. gr.Slider( minimum=0, maximum=1, value=0.5, step=0.1 ) This gives values such as: 0.0 0.1 0.2 0.3 ... 1.0 This can be useful for parameters that should have predictable increments. Dropdown A dropdown allows users to select an option. model = gr.Dropdown( choices=["Model A", "Model B", "Model C"], label="Choose a model" ) You can provide a default: model = gr.Dropdown( choices=["Model A", "Model B", "Model C"], value="Model A", label="Choose a model" ) Dropdowns are particularly useful when there are enough options that displaying all of them at once would take up too much space. Radio Radio is useful when the user should select one option from a small group. language = gr.Radio( choices=["Python", "JavaScript", "Java"], label="Programming Language" ) This is often more convenient than a dropdown when there are only a few choices and the options should remain visible. Checkbox A checkbox represents a Boolean choice. subscribe = gr.Checkbox( label="Subscribe to updates" ) The Python function receives a Boolean value: True or: False For example: def get_status(subscribed): if subscribed: return "You are subscribed." return "You are not subscribed." CheckboxGroup If the user can choose multiple options, use a checkbox group. interests = gr.CheckboxGroup( choices=[ "AI", "Web Development", "Data