By default, share=False, which means that your server is only running locally.
Gradio demos can be easily shared publicly by setting share=True in the launch(). This generates a public, shareable link !
The link is served through the Gradio Share Servers, these servers are only a proxy for your local server, and do not store any data sent through your app.
Keep in mind that share links are publicly accessible, meaning that anyone can use your model for prediction!
Therefore, make sure not to expose any sensitive information through the functions you write, or allow any critical changes to occur on your device.
As an alternative to using share links, you can use use SSH port-forwarding to share your local server with specific users.
Hosting on HF Spaces
If you'd like to have a permanent link to your Gradio demo on the internet, use Hugging Face Spaces. Hugging Face Spaces provides the infrastructure to permanently host your machine learning model for free!
Embedding Hosted Spaces
Once you have hosted your app on Hugging Face Spaces (or on your own server), you may want to embed the demo on a different website, such as your blog or your portfolio.
Embedding an interactive demo allows people to try out the machine learning model that you have built, without needing to download or install anything — right in their browser! The best part is that you can embed interactive demos even in static websites, such as GitHub pages.
Embedding with Web Components
Web components typically offer a better experience to users than IFrames. Web components load lazily, meaning that they won't slow down the loading time of your website, and they automatically adjust their height based on the size of the Gradio app.
There are two ways to embed your Gradio demos. You can find quick links to both options directly on the Hugging Face Space page, in the "Embed this Space" dropdown option:
To embed with Web Components:
Import the gradio JS library into into your site by adding the script below in your site (replace 4.37.2 in the URL with the library version of Gradio you are using).
element where you want to place the app. Set the src= attribute to your Space's embed URL, which you can find in the "Embed this Space" button. For example:
You can also customize the appearance and behavior of your web component with attributes that you pass into the tag:
src: as we've seen, the src attributes links to the URL of the hosted Gradio demo that you would like to embed
space: an optional shorthand if your Gradio demo is hosted on Hugging Face Space. Accepts a username/space_name instead of a full URL. Example: gradio/Echocardiogram-Segmentation. If this attribute attribute is provided, then src does not need to be provided.
control_page_title: a boolean designating whether the html title of the page should be set to the title of the Gradio app (by default "false")
initial_height: the initial height of the web component while it is loading the Gradio app, (by default "300px"). Note that the final height is set based on the size of the Gradio app.
container: whether to show the border frame and information about where the Space is hosted (by default "true")
info: whether to show just the information about where the Space is hosted underneath the embedded app (by default "true")
autoscroll: whether to autoscroll to the output when prediction has finished (by default "false")
eager: whether to load the Gradio app as soon as the page loads (by default "false")
theme_mode: whether to use the dark, light, or default system theme mode (by default "system")
render: an event that is triggered once the embedded space has finished rendering.
Embedding with IFrames
To embed with IFrames instead (if you cannot add javascript to your website, for example), add this element:
Again, you can find the src= attribute to your Space's embed URL, which you can find in the "Embed this Space" button.
Note: if you use IFrames, you'll probably want to add a fixed height attribute and set style="border:0;" to remove the border. In addition, if your app requires permissions such as access to the webcam or the microphone, you'll need to provide that as well using the allow attribute.
API Page
You can use almost any Gradio app as an API! In the footer of a Gradio app like this one, you'll see a "Use via API" link.
This is a page that lists the endpoints that can be used to query the Gradio app, via our supported clients: either the Python client, or the JavaScript client. For each endpoint, Gradio automatically generates the parameters and their types, as well as example inputs, like this.
The endpoints are automatically created when you launch a Gradio Interface. If you are using Gradio Blocks, you can also set up a Gradio API page, though we recommend that you explicitly name each event listener, such as
btn.click(add, [num1, num2], output, api_name="addition")
This will add and document the endpoint /api/addition/ to the automatically generated API page. Otherwise, your API endpoints will appear as "unnamed" endpoints.
Accessing the Network Request Directly
When a user makes a prediction to your app, you may need the underlying network request, in order to get the request headers (e.g. for advanced authentication), log the client's IP address, getting the query parameters, or for other reasons. Gradio supports this in a similar manner to FastAPI: simply add a function parameter whose type hint is gr.Request and Gradio will pass in the network request as that parameter. Here is an example:
import gradio as gr
def echo(text, request: gr.Request):
if request:
print("Request headers dictionary:", request.headers)
print("IP address:", request.client.host)
print("Query parameters:", dict(request.query_params))
return text
io = gr.Interface(echo, "textbox", "textbox").launch()
Mounting Within Another FastAPI App
In some cases, you might have an existing FastAPI app, and you'd like to add a path for a Gradio demo. You can easily do this with gradio.mount_gradio_app().
Here's a complete example:
from fastapi import FastAPI
import gradio as gr
CUSTOM_PATH = "/gradio"
app = FastAPI()
@app.get("/")
def read_main():
return {"message": "This is your main app"}
io = gr.Interface(lambda x: "Hello, " + x + "!", "textbox", "textbox")
app = gr.mount_gradio_app(app, io, path=CUSTOM_PATH)
# Run this from the terminal as you would normally start a FastAPI app: `uvicorn run:app`
# and navigate to http://localhost:8000/gradio in your browser.
Authentication
Password-protected app
You may wish to put an authentication page in front of your app to limit who can open your app. With the auth= keyword argument in the launch() method, you can provide a tuple with a username and password, or a list of acceptable username/password tuples; Here's an example that provides password-based authentication for a single user named "admin":
demo.launch(auth=("admin", "pass1234"))
For more complex authentication handling, you can even pass a function that takes a username and password as arguments, and returns True to allow access, False otherwise.
Here's an example of a function that accepts any login where the username and password are the same:
If you have multiple users, you may wish to customize the content that is shown depending on the user that is logged in. You can retrieve the logged in user by accessing the network request directly as discussed above, and then reading the .username attribute of the request. Here's an example:
import gradio as gr
def update_message(request: gr.Request):
return f"Welcome, {request.username}"
with gr.Blocks() as demo:
m = gr.Markdown()
demo.load(update_message, None, m)
demo.launch(auth=[("Abubakar", "Abubakar"), ("Ali", "Ali")])
Note: For authentication to work properly, third party cookies must be enabled in your browser. This is not the case by default for Safari or for Chrome Incognito Mode.
If users visit the/logout page of your Gradio app, they will automatically be logged out and session cookies deleted. This allows you to add logout functionality to your Gradio app as well. Let's update the previous example to include a log out button:
import gradio as gr
def update_message(request: gr.Request):
return f"Welcome, {request.username}"
with gr.Blocks() as demo:
m = gr.Markdown()
logout_button = gr.Button("Logout", link="/logout")
demo.load(update_message, None, m)
demo.launch(auth=[("Pete", "Pete"), ("Dawood", "Dawood")])
Note: Gradio's built-in authentication provides a straightforward and basic layer of access control but does not offer robust security features for applications that require stringent access controls (e.g. multi-factor authentication, rate limiting, or automatic lockout policies).
authenticate with external OAuth providers
mount your Gradio app within a FastAPI app
write an authentication function, which gets the user's username from the OAuth provider and returns it. This function should be passed to the auth_dependency parameter in gr.mount_gradio_app.
from fastapi import FastAPI, Request
import gradio as gr
app = FastAPI()
def get_user(request: Request):
return request.headers.get("user")
demo = gr.Interface(lambda s: f"Hello {s}!", "textbox", "textbox")
app = gr.mount_gradio_app(app, demo, path="/demo", auth_dependency=get_user)
if __name__ == '__main__':
uvicorn.run(app)
Sharing the App
By default, share=False, which means that your server is only running locally. Gradio demos can be easily shared publicly by setting
share=Truein thelaunch(). This generates a public, shareable link ! The link is served through the Gradio Share Servers, these servers are only a proxy for your local server, and do not store any data sent through your app.Keep in mind that share links are publicly accessible, meaning that anyone can use your model for prediction! Therefore, make sure not to expose any sensitive information through the functions you write, or allow any critical changes to occur on your device.
As an alternative to using share links, you can use use SSH port-forwarding to share your local server with specific users.
Hosting on HF Spaces
If you'd like to have a permanent link to your Gradio demo on the internet, use Hugging Face Spaces. Hugging Face Spaces provides the infrastructure to permanently host your machine learning model for free!
Embedding Hosted Spaces
Once you have hosted your app on Hugging Face Spaces (or on your own server), you may want to embed the demo on a different website, such as your blog or your portfolio. Embedding an interactive demo allows people to try out the machine learning model that you have built, without needing to download or install anything — right in their browser! The best part is that you can embed interactive demos even in static websites, such as GitHub pages.
Embedding with Web Components
Web components typically offer a better experience to users than IFrames. Web components load lazily, meaning that they won't slow down the loading time of your website, and they automatically adjust their height based on the size of the Gradio app.
There are two ways to embed your Gradio demos. You can find quick links to both options directly on the Hugging Face Space page, in the "Embed this Space" dropdown option:
To embed with Web Components:
Import the gradio JS library into into your site by adding the script below in your site (replace 4.37.2 in the URL with the library version of Gradio you are using).
Add
element where you want to place the app. Set the src= attribute to your Space's embed URL, which you can find in the "Embed this Space" button. For example:
You can see examples of how web components look on the Gradio landing page.
You can also customize the appearance and behavior of your web component with attributes that you pass into the tag:
Embedding with IFrames
To embed with IFrames instead (if you cannot add javascript to your website, for example), add this element:
Again, you can find the src= attribute to your Space's embed URL, which you can find in the "Embed this Space" button.
Note: if you use IFrames, you'll probably want to add a fixed height attribute and set
style="border:0;"to remove the border. In addition, if your app requires permissions such as access to the webcam or the microphone, you'll need to provide that as well using the allow attribute.API Page
You can use almost any Gradio app as an API! In the footer of a Gradio app like this one, you'll see a "Use via API" link.
This is a page that lists the endpoints that can be used to query the Gradio app, via our supported clients: either the Python client, or the JavaScript client. For each endpoint, Gradio automatically generates the parameters and their types, as well as example inputs, like this.
The endpoints are automatically created when you launch a Gradio Interface. If you are using Gradio Blocks, you can also set up a Gradio API page, though we recommend that you explicitly name each event listener, such as
btn.click(add, [num1, num2], output, api_name="addition") This will add and document the endpoint /api/addition/ to the automatically generated API page. Otherwise, your API endpoints will appear as "unnamed" endpoints.
Accessing the Network Request Directly
When a user makes a prediction to your app, you may need the underlying network request, in order to get the request headers (e.g. for advanced authentication), log the client's IP address, getting the query parameters, or for other reasons. Gradio supports this in a similar manner to FastAPI: simply add a function parameter whose type hint is gr.Request and Gradio will pass in the network request as that parameter. Here is an example:
Mounting Within Another FastAPI App
In some cases, you might have an existing FastAPI app, and you'd like to add a path for a Gradio demo. You can easily do this with gradio.mount_gradio_app().
Here's a complete example:
Authentication
Password-protected app
You may wish to put an authentication page in front of your app to limit who can open your app. With the auth= keyword argument in the launch() method, you can provide a tuple with a username and password, or a list of acceptable username/password tuples; Here's an example that provides password-based authentication for a single user named "admin":
For more complex authentication handling, you can even pass a function that takes a username and password as arguments, and returns True to allow access, False otherwise.
Here's an example of a function that accepts any login where the username and password are the same:
If you have multiple users, you may wish to customize the content that is shown depending on the user that is logged in. You can retrieve the logged in user by accessing the network request directly as discussed above, and then reading the .username attribute of the request. Here's an example:
Note: For authentication to work properly, third party cookies must be enabled in your browser. This is not the case by default for Safari or for Chrome Incognito Mode.
If users visit the
/logoutpage of your Gradio app, they will automatically be logged out and session cookies deleted. This allows you to add logout functionality to your Gradio app as well. Let's update the previous example to include a log out button:Note: Gradio's built-in authentication provides a straightforward and basic layer of access control but does not offer robust security features for applications that require stringent access controls (e.g. multi-factor authentication, rate limiting, or automatic lockout policies).
authenticate with external OAuth providers
mount your Gradio app within a FastAPI app