gr.load() — one line to a working UI for any HF model or Space

A hosted ML demo is one function call away: gr.load() reconstructs the UI, .load() fires when your page opens.

What if you never had to build the UI at all — because somebody on the Hub already did?

What it does

gr.load("models/google/vit-base-patch16-224") fetches a model's config from the Hugging Face Hub, figures out the right input and output components for its pipeline type, and hands you a working gr.Interface. Loading "spaces/…" instead reconstructs a whole Blocks app by talking to the running Space's API. There are two different "load"s in Gradio: this module-level factory, and demo.load() — an event listener on Blocks that fires when the page opens, perfect for seeding state. Same word, two jobs.

Why it matters

It collapses the distance from "I found a model on the Hub" to "I am clicking that model in my browser" to a single line. Before 4.0 you could not even get here — Interface.load() existed since 2.9 but the API surface was clunky, and 4.0 removed it in favor of this function. For a quick demo, a prototype, or an A/B of two checkpoints, rebuilding the UI by hand is wasted work. The flip side: you inherit whatever UI the upstream author wrote, and the Inference API route means your requests leave your machine.

Examples

import gradio as gr

# One line: fetch the model's config from the Hub and build an interface
# around the Inference API call.
demo = gr.load("models/google/vit-base-patch16-224")
demo.launch()

Console:
Fetching model from: https://huggingface.co/google/vit-base-patch16-224
* Running on local URL:  http://127.0.0.1:7860

Rendered UI (a gr.Interface, verified on gradio 6.27.0):
- Image input labeled "Input Image" (left column)
- Label output labeled "Classification" (right column)
- Clear / Submit / Flag buttons in a bottom row
- A small "Use via API" link in the footer — the load is a real, callable API client under the hood

Verified: this exact snippet ran against gradio 6.27.0; gr.load returned a gr.Interface with components Image(label='Input Image') and Label(label='Classification'). The 'Fetching model from:' line is gr.load's own console output.

import gradio as gr

# src is inferred from the prefix: "spaces/..." loads a whole Space as Blocks.
demo = gr.load("spaces/gradio/question-answering")
demo.launch()

Console:
Fetching Space from: https://huggingface.co/spaces/gradio/question-answering
Loaded as API: https://gradio-question-answering.hf.space
* Running on local URL:  http://127.0.0.1:7860

Rendered UI (a gr.Blocks, verified): two Textbox inputs labeled "Context Paragraph" and "Question", a submit Button, and two read-only Textbox outputs labeled "Answer" and "Score". The Space's own layout and labels survive the trip; queries are proxied to the live Space.

Verified on gradio 6.27.0: returned Blocks, not Interface — Space loads reconstruct the upstream layout, model loads return Interface.

import gradio as gr

# The other 'load': an event that fires when the page opens.
with gr.Blocks() as dashboard:
    gr.Markdown("## Visitor dashboard")
    hits = gr.Number(label="Sessions", value=0, interactive=False)
    status = gr.Textbox(label="Last event", value="waiting…", interactive=False)

    def on_open():
        return 1, "demo.load fired on page open"

    dashboard.load(on_open, inputs=None, outputs=[hits, status])

dashboard.launch()

Console:
* Running on local URL:  http://127.0.0.1:44065

Rendered UI (verified): Markdown header "Visitor dashboard", a Number box labeled "Sessions" (read-only), and a Textbox labeled "Last event". The moment a browser tab connects, on_open() runs and the components populate — no click needed.

Verified: constructed and launched on gradio 6.27.0 with launch(prevent_thread_lock=True); the 'Running on local URL' line above is the captured stdout.

import gradio as gr

demo = gr.load(
    "models/google/vit-base-patch16-224",
    title="My Own Title",
    description="Wrapped checkpoint, my house style",
)
demo.launch()

Console:
Fetching model from: https://huggingface.co/google/vit-base-patch16-224
* Running on local URL:  http://127.0.0.1:7860

Rendered UI: identical Input Image → Classification layout, but the page header now reads "My Own Title" and the custom description sits under it. Verified in Python: demo.title == "My Own Title".

Verified: kwargs like title/description pass through to the gr.Interface constructor for model loads.

Flags

Flag	Meaning
`name`	Repo id like "models/org/model" or "spaces/org/space" — the prefix routes the loader; bare repo ids need src.
`src`	"models" (Inference API via a reconstructed Interface) or "spaces" (proxy a live Space, returns Blocks).
`token`	HF token for private repos; falls back to the HF_TOKEN env var. For Spaces, only pass a token you'd trust the Space with.
`accept_token`	Renders a Textbox (or works with a gr.LoginButton) so visitors supply their own token — your server never holds a secret.
`provider`	Third-party inference provider ("replicate", "sambanova", "fal-ai", …) — models only, routed through the Inference API.
`**kwargs`	Extra Interface/ChatInterface constructor args (title, description, examples) applied to the rebuilt UI.
`demo.load(fn, inputs, outputs)`	The Blocks.load event listener: fires once when a browser session opens the page.

Born as Interface.load, reborn in 4.0

Loading models from the Hub shipped as gr.Interface.load() back in the Gradio 2.x days (2022), grew Space-loading and pipeline coverage through 3.x (private Spaces in 3.8, image-to-text and conversational pipelines in 3.17.0), and was removed in 4.0 — where the module-level gr.load() took over the factory role and Blocks.load() became purely the page-open event listener.

One name split into two APIs

4.0's migration notes say it directly: "Blocks.load() can only be used as an instance method to attach an event that runs when the page loads. To use the class method, use gr.load() instead." The split tripped up enough people that the migration guide had to spell it out.

Under the hood: how the magic reconstruction works

For "models/...", gr.load() calls the Hub, reads the model card's inference config (pipeline type, inputs/outputs), maps it to Gradio components, and assembles a gr.Interface whose fn is an InferenceClient call. For "spaces/...", it fetches the Space's config JSON from its *.hf.space endpoint, rebuilds the component tree locally, and wires every event to the Space's existing queue — your app becomes a mirror with a URL rewrite. That is why custom css/js/head of the upstream app are intentionally NOT carried over (the docstring says so): the reflection carries the component tree, not the page chrome.

Fun facts

In Gradio 3.x the model loader lived on the class itself — gr.Interface.load("models/...") — and 4.0 deleted it, forcing every tutorial and README on the Hub to update their one-liners to gr.load().
gr.load_chat() is the specialized sibling: point it at any OpenAI-compatible endpoint and you get a full gr.ChatInterface without writing a handler — the chatbot twin of gr.load().

Pros

A working ML demo in one line — no model code, no UI code
kwargs (title, description, examples) let you restyle the rebuilt UI
accept_token and a gr.LoginButton keep private models usable without ever handling secrets yourself

Cons

You inherit upstream quirks: layout, queue limits, and API changes are out of your control
Needs a reachable Hugging Face endpoint at construction time — no network, no app
Space loads don't carry over upstream css/js/head, so the clone can look plainer than the original

Takeaways

One line of gr.load() replaces an afternoon of boilerplate: model → Interface, Space → Blocks.
Prefix the repo id ("models/…", "spaces/…") and let the loader infer src — bare ids need an explicit src.
demo.load() is a different thing: the event listener that fires when a browser opens your page.
Wrap loaded Spaces behind your own error handling — upstream downtime becomes your downtime.
Never hardcode your HF token into a public demo; use accept_token or a gr.LoginButton instead.