# Deploy a Gradio App to Hugging Face Spaces

> Write a minimal Gradio app.py, add requirements.txt and a Space README, create the Space, push with the hf CLI, set secrets, and read the build logs.

- Canonical: https://guides-ai.com/guides/deploy-gradio-app-hugging-face-spaces/
- Plate 16.10 · Topic: Hugging Face (https://guides-ai.com/topics/huggingface/)
- Published: 12 Oct 2026 · 3 min read
- Source site: guides-ai — https://guides-ai.com/

A Space is a git repo that rebuilds and restarts on every push. For Gradio you need three files — `app.py`, `requirements.txt`, and a `README.md` with Space metadata — then one push.

## 1. Write app.py

```python
import gradio as gr

def greet(name):
    return "Hello " + name + "!"

demo = gr.Interface(fn=greet, inputs="textbox", outputs="textbox")
demo.launch()
```

`gr.Interface` wraps your function in a UI; `demo.launch()` serves it on port 7860, which Spaces expects. Gradio needs Python 3.10 or higher. For a custom layout use `gr.Blocks`, but `demo.launch()` stays the same. The current [Gradio quickstart](https://www.gradio.app/guides/quickstart) has the full API.

## 2. Add requirements.txt and README

```text
gradio
```

Lists the pip packages the Space installs at build time; pin a version (`gradio==6.30.0`, the current release — use whatever is latest when you build) once it works. The `README.md` YAML header configures the Space:

```yaml
---
title: My Demo
emoji: 🤗
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 6.30.0
app_file: app.py
pinned: false
---
```

`sdk: gradio` and `app_file` are the load-bearing keys; set `sdk_version` to the current Gradio release (check [the Gradio changelog](https://www.gradio.app/changelog)).

## 3. Create the Space

```bash
hf repos create my-demo --repo-type space --sdk gradio
```

Creates `your-username/my-demo` as a Gradio Space. The flag is `--sdk` (not `--space-sdk`), and the subcommand is `repos`. You can also use **New Space** in the web UI.

## 4. Push your files

```bash
hf upload your-username/my-demo . --repo-type space
```

Uploads the current folder to the Space root; each push triggers a rebuild. Prefer git? Clone the Space repo and `git push` — the Hub treats both the same.

## 5. Set secrets and hardware

Never hard-code keys. In the Space's Settings add a **secret**, then read it at runtime:

```python
import os
token = os.getenv("HF_TOKEN")
```

Hardware: the default CPU Basic has no hourly cost, but per the [Spaces overview](https://huggingface.co/docs/hub/spaces-overview), creating a Gradio Space now requires a paid plan — free personal accounts in good standing may instead host up to 2 Gradio Spaces on ZeroGPU. Set GPU tiers in Settings only if your plan allows it.

## 6. Read the build logs

The Space page shows a **Building** then **Running** badge with a live log. Open it on every push — a red build almost always names the missing package or the traceback line.

**If it fails:**

- **Build failed: `ModuleNotFoundError`** — the import is not in `requirements.txt`. Add it and push again.
- **"Runtime error" after build** — `app.py` crashed on launch. Check the container log; common causes are a wrong `app_file` path or a missing secret read with `os.getenv`.
- **Space shows "Sleeping"** — on free hardware a Space sleeps when unused and wakes on the next visit. Upgrade to paid hardware for always-on.

Next: [download models with the hf CLI](/guides/hugging-face-cli-download-models/) · [a minimal RAG app in Python](/guides/rag-with-python-minimal/) · [pick an AI model](/guides/pick-an-ai-model/).