Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 37 ยท Sharing and Deployment

Deploying Gradio to Hugging Face Spaces

Publish a Gradio app on Hugging Face Spaces: app.py, requirements.txt, README metadata, secrets, hardware, plus other hosting options and a runnable config checker.

A demo on your laptop helps nobody else. Hugging Face Spaces is the most common home for Gradio apps: you push a few files to a Git repository and the platform builds, runs and serves them at a public URL, with free CPU hardware to start. This lesson covers the files a Space needs, how secrets and hardware work, and the other ways to host the same app.

Real deployment needs your own account and network access, so the commands here are read-only. The runnable blocks build and validate the Space's metadata in plain Python, which is a good way to see exactly what the platform reads.

The three files

A Gradio Space is a Git repository with at least:

TEXT
my-demo/
  app.py             # your Gradio code; defines and launches the demo
  requirements.txt   # extra Python packages (not gradio itself)
  README.md          # begins with a YAML block that configures the Space

app.py is a normal Gradio script. The platform runs it and expects it to listen on the port it provides. A plain demo.launch() does the right thing; do not set share=True or a fixed server_port.

Python
import gradio as gr

def greet(name):
    return f"Hello, {name}!"

demo = gr.Interface(greet, "text", "text")

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

requirements.txt lists everything besides gradio, one per line, ideally pinned: transformers==4.46.0, torch, pillow. The sdk_version in the README decides the Gradio version, so do not add gradio here unless you need a different one.

README.md starts with a front-matter block between lines of three dashes:

YAML
---
title: Hello Demo
emoji: ๐Ÿ‘‹
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 5.9.1
app_file: app.py
pinned: false
license: mit
---

sdk: gradio selects the Gradio runtime, app_file names the entry script, emoji/colorFrom/colorTo style the card on your profile, and short_description adds a one-line subtitle. Everything after the second --- is ordinary Markdown shown on the Space's page.

Creating and pushing the Space

  1. Create a Space on the website: choose a name, the Gradio SDK, a license and the free "CPU basic" hardware.
  2. Clone the new empty repository, add your three files, commit and push. Or use the shortcut gradio deploy from your project folder, which asks a few questions and creates the Space for you.
  3. Watch the Logs tab. The Space installs the requirements, then runs app.py. When logs say it is running on a URL, the page works at https://<user>-<space-name>.hf.space.

A Space sleeps after a period of no traffic on free hardware and takes a minute to wake. Paid upgrades (a GPU such as an A10G, or "always on") are chosen in the Space's settings.

Secrets and variables

Never commit tokens. In Settings โ†’ Variables and secrets, add a secret such as OPENAI_API_KEY; the Space provides it to your code as an environment variable:

Python
import os
api_key = os.environ.get("OPENAI_API_KEY")
if not api_key:
    raise RuntimeError("Set OPENAI_API_KEY in the Space settings")

Secrets are hidden from visitors and are not copied when someone duplicates your Space. Plain variables are visible to anyone who can read the Space settings; use them for non-sensitive configuration.

Checking a Space configuration (stand-in)

The block below parses a README front-matter block and checks it, which is a tiny version of the checks the platform makes. It uses only plain Python.

Python Validate Space metadata

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 first check prints ['ok']; the second reports that app.py is not in the repository, the most common cause of a "No application file" error on a new Space.

Pinning requirements

Unpinned requirements make builds that worked yesterday fail today. This second block checks a requirements file for unpinned lines.

Python Find unpinned requirements

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.

torch and pillow>=10 are flagged. A range such as >=10 is not always wrong, but exact pins make rebuilds reproducible; update them deliberately when you test a new version.

Other places to host

Option Good for Notes
Hugging Face Space Public demos, portfolios Free CPU, paid GPU, sleeps when idle
Docker container Any cloud Run python app.py with server_name="0.0.0.0"; expose port 7860
Your own server Internal tools Run behind nginx or Caddy with HTTPS; keep websockets (and streaming) enabled
Mounted in FastAPI Existing web apps gr.mount_gradio_app(app, demo, path="/demo"), see structuring larger apps
Notebook Teaching demo.launch() shows the app inline

When you use a reverse proxy, forward the WebSocket/streaming headers and set root_path so links and file uploads use the public URL. Keep max_file_size modest, and put the app behind authentication if it exposes anything private.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which file's front-matter sets sdk and app_file for a Space?

    The YAML block at the top of README.md configures the Space.
  2. 2. Where should an API key for a Space be stored?

    Secrets are injected as environment variables and are not visible to visitors.
  3. 3. What should requirements.txt NOT normally contain?

    The Gradio version is set by sdk_version in the README.
  4. 4. Why use server_name="0.0.0.0" in a Docker container?

    The default 127.0.0.1 is reachable only from inside the container.

Summary

  • A Gradio Space needs app.py, requirements.txt and a README.md with a YAML header.
  • Use secrets for keys; pin requirements; let sdk_version choose Gradio.
  • Free hardware sleeps when idle; GPUs and always-on are paid settings.
  • Docker, your own server or a FastAPI mount are alternatives when you need more control.

Next: Authentication, Secrets and Security