Introducing Gradio 5.0
Read MoreIntroducing Gradio 5.0
Read MoreWhen building a Gradio application with gr.Blocks()
, you may want to share certain values between users (e.g. a count of visitors to your page), or persist values for a single user across certain interactions (e.g. a chat history). This referred to as state and there are three general ways to manage state in a Gradio application:
Global state in Gradio apps is very simple: any variable created outside of a function is shared globally between all users.
This makes managing global state very simple and without the need for external services. For example, in this application, the visitor_count
variable is shared between all users
import gradio as gr
# Shared between all users
visitor_count = 0
def increment_counter():
global visitor_count
visitor_count += 1
return visitor_count
with gr.Blocks() as demo:
number = gr.Textbox(label="Total Visitors", value="Counting...")
demo.load(increment_counter, inputs=None, outputs=number)
demo.launch()
This means that any time you do not want to share a value between users, you should declare it within a function. But what if you need to share values between function calls, e.g. a chat history? In that case, you should use one of the subsequent approaches to manage state.
Gradio supports session state, where data persists across multiple submits within a page session. To reiterate, session data is not shared between different users of your model, and does not persist if a user refreshes the page to reload the Gradio app. To store data in a session state, you need to do three things:
gr.State()
object. If there is a default value to this stateful object, pass that into the constructor. Note that gr.State
objects must be deepcopy-able, otherwise you will need to use a different approach as described below.State
object as an input and output as needed.Let's take a look at a simple example. We have a simple checkout app below where you add items to a cart. You can also see the size of the cart.
import gradio as gr
with gr.Blocks() as demo:
cart = gr.State([])
items_to_add = gr.CheckboxGroup(["Cereal", "Milk", "Orange Juice", "Water"])
def add_items(new_items, previous_cart):
cart = previous_cart + new_items
return cart
gr.Button("Add Items").click(add_items, [items_to_add, cart], cart)
cart_size = gr.Number(label="Cart Size")
cart.change(lambda cart: len(cart), cart, cart_size)
demo.launch()
Notice how we do this with state:
gr.State()
object, initialized here to be an empty list..change
listener to cart, that uses the state variable as input as well.You can think of gr.State
as an invisible Gradio component that can store any kind of value. Here, cart
is not visible in the frontend but is used for calculations.
The .change
listener for a state variable triggers after any event listener changes the value of a state variable. If the state variable holds a sequence (like a list
, set
, or dict
), a change is triggered if any of the elements inside change. If it holds an object or primitive, a change is triggered if the hash of the value changes. So if you define a custom class and create a gr.State
variable that is an instance of that class, make sure that the the class includes a sensible __hash__
implementation.
The value of a session State variable is cleared when the user refreshes the page. The value is stored on in the app backend for 60 minutes after the user closes the tab (this can be configured by the delete_cache
parameter in gr.Blocks
).
Learn more about State
in the docs.
What about objects that cannot be deepcopied?
As mentioned earlier, the value stored in gr.State
must be deepcopy-able. If you are working with a complex object that cannot be deepcopied, you can take a different approach to manually read the user's session_hash
and store a global dictionary
with instances of your object for each user. Here's how you would do that:
import gradio as gr
class NonDeepCopyable:
def __init__(self):
from threading import Lock
self.counter = 0
self.lock = Lock() # Lock objects cannot be deepcopied
def increment(self):
with self.lock:
self.counter += 1
return self.counter
# Global dictionary to store user-specific instances
instances = {}
def initialize_instance(request: gr.Request):
instances[request.session_hash] = NonDeepCopyable()
return "Session initialized!"
def cleanup_instance(request: gr.Request):
if request.session_hash in instances:
del instances[request.session_hash]
def increment_counter(request: gr.Request):
if request.session_hash in instances:
instance = instances[request.session_hash]
return instance.increment()
return "Error: Session not initialized"
with gr.Blocks() as demo:
output = gr.Textbox(label="Status")
counter = gr.Number(label="Counter Value")
increment_btn = gr.Button("Increment Counter")
increment_btn.click(increment_counter, inputs=None, outputs=counter)
# Initialize instance when page loads
demo.load(initialize_instance, inputs=None, outputs=output)
# Clean up instance when page is closed/refreshed
demo.close(cleanup_instance)
demo.launch()
Gradio also supports browser state, where data persists in the browser's localStorage even after the page is refreshed or closed. This is useful for storing user preferences, settings, API keys, or other data that should persist across sessions. To use local state:
gr.BrowserState
object. You can optionally provide an initial default value and a key to identify the data in the browser's localStorage.gr.State
component in event listeners as inputs and outputs.Here's a simple example that saves a user's username and password across sessions:
import random
import string
import gradio as gr
import time
with gr.Blocks() as demo:
gr.Markdown("Your Username and Password will get saved in the browser's local storage. "
"If you refresh the page, the values will be retained.")
username = gr.Textbox(label="Username")
password = gr.Textbox(label="Password", type="password")
btn = gr.Button("Generate Randomly")
local_storage = gr.BrowserState(["", ""])
saved_message = gr.Markdown("✅ Saved to local storage", visible=False)
@btn.click(outputs=[username, password])
def generate_randomly():
u = "".join(random.choices(string.ascii_letters + string.digits, k=10))
p = "".join(random.choices(string.ascii_letters + string.digits, k=10))
return u, p
@demo.load(inputs=[local_storage], outputs=[username, password])
def load_from_local_storage(saved_values):
print("loading from local storage", saved_values)
return saved_values[0], saved_values[1]
@gr.on([username.change, password.change], inputs=[username, password], outputs=[local_storage])
def save_to_local_storage(username, password):
return [username, password]
@gr.on(local_storage.change, outputs=[saved_message])
def show_saved_message():
timestamp = time.strftime("%I:%M:%S %p")
return gr.Markdown(
f"✅ Saved to local storage at {timestamp}",
visible=True
)
demo.launch()