Hugging Face Spaces

Hugging Face Spaces provides free infrastructure to permanently host your Gradio apps. Deploy in minutes using the CLI or web interface, with support for GPU hardware, secrets management, and automatic updates.

Overview

Hugging Face Spaces offers:

Free hosting: Permanent URLs for your demos
No cold starts: Apps stay warm and responsive
GPU support: Access to various GPU options
Easy deployment: CLI or web-based upload
Automatic updates: Sync with GitHub for CI/CD
Secrets management: Secure environment variables
Community: Discover and share demos

Quick start

Deploy your Gradio app in under 2 minutes:

Create a Hugging Face account

Deploy from terminal

Run this command in your app directory:

gradio deploy

The CLI will:

Ask for your Space name
Upload all files (respecting .gitignore)
Launch your app on Spaces

Access your app

Your app will be live at:

https://huggingface.co/spaces/username/space-name

Deployment methods

Method 1: CLI deployment (recommended)

The fastest way to deploy:

cd my-gradio-app
gradio deploy

You’ll be prompted for:

Space name
Whether to set up GitHub Actions (for auto-updates)
Hardware tier (CPU or GPU)

Update an existing Space

Simply run gradio deploy again in the same directory:

gradio deploy

Enable GitHub Actions

Automate deployments on every git push:

gradio deploy --github-actions

This creates a GitHub Actions workflow that deploys to Spaces automatically.

Method 2: Web interface

Deploy via drag-and-drop:

Create a new Space

Go to huggingface.co/new-space

Choose settings

Pick a name
Select “Gradio” as the SDK
Choose hardware (CPU or GPU)

Upload files

Drag and drop your app folder, or clone via Git

Method 3: Git workflow

For version control and collaboration:

# Create and clone Space
huggingface-cli repo create my-space --type space --space-sdk gradio
git clone https://huggingface.co/spaces/username/my-space
cd my-space

# Add your files
cp -r ../my-gradio-app/* .

# Commit and push
git add .
git commit -m "Initial commit"
git push

App structure

A typical Gradio Space contains:

my-space/
├── app.py              # Main Gradio app (required)
├── requirements.txt    # Python dependencies
├── README.md          # Space description and settings
├── .gitignore         # Files to ignore
└── examples/          # Example files (optional)

Example app.py

import gradio as gr

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

demo = gr.Interface(
    fn=greet,
    inputs=gr.Textbox(label="Name"),
    outputs=gr.Textbox(label="Greeting"),
    title="Hello World",
    description="A simple greeting app"
)

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

Example requirements.txt

gradio>=4.0.0
transformers
torch
pillow

README.md metadata

Configure your Space with YAML frontmatter:

---
title: My Gradio App
emoji: 🚀
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 4.44.0
app_file: app.py
pinned: false
license: mit
---

# My Gradio App

Description of your app...

Hardware options

CPU (free)

Default tier, suitable for:

Text processing
Simple data analysis
Lightweight models
Educational demos

GPU (paid)

For compute-intensive tasks:

Hardware	vCPU	RAM	GPU VRAM	Price/hour
T4 Small	4	15 GB	16 GB	$0.60
T4 Medium	8	30 GB	16 GB	$0.90
A10G Small	4	15 GB	24 GB	$1.05
A10G Large	12	46 GB	24 GB	$3.15
A100 Large	12	142 GB	40 GB	$4.13

Change hardware via UI

Go to your Space settings
Click “Hardware”
Select new tier
Click “Update hardware”

Change hardware via CLI

from huggingface_hub import HfApi

api = HfApi()
api.request_space_hardware(
    repo_id="username/space-name",
    hardware="a10g-small"
)

Sleep timeout

GPU Spaces automatically sleep after inactivity:

from huggingface_hub import HfApi

api = HfApi()
api.set_space_sleep_time(
    repo_id="username/space-name",
    sleep_time=3600  # 1 hour
)

Environment variables and secrets

Add secrets via UI

Go to Space settings
Click “Variables and secrets”
Add name and value
Click “Save”

Add secrets via CLI

from huggingface_hub import HfApi

api = HfApi()
api.add_space_secret(
    repo_id="username/space-name",
    key="API_KEY",
    value="your-secret-value"
)

Use secrets in code

import os
import gradio as gr

API_KEY = os.environ.get("API_KEY")

def call_api(text):
    # Use API_KEY here
    return process_with_api(text, API_KEY)

demo = gr.Interface(
    fn=call_api,
    inputs="text",
    outputs="text"
)

demo.launch()

Never commit secrets to your repository! Always use environment variables.

Duplicate Spaces programmatically

Create private copies of Spaces for unlimited API usage:

from gradio_client import Client

# Duplicate and connect
client = Client.duplicate(
    "abidlabs/whisper",
    token="hf_...",
    hardware="t4-small"  # Optional
)

# Use the duplicated Space
result = client.predict("audio.wav")

Benefits:

No rate limits
Guaranteed availability
Custom hardware
Private usage

Custom domains

Pro users can add custom domains:

Go to Space settings
Click “Domains”
Add your domain (e.g., demo.mycompany.com)
Update DNS records as shown
Wait for verification

Persistent storage

Spaces are stateless by default. For persistent data:

Use Hugging Face Datasets

from huggingface_hub import hf_hub_download
import json

# Download data
data_file = hf_hub_download(
    repo_id="username/my-dataset",
    filename="data.json",
    repo_type="dataset"
)

with open(data_file) as f:
    data = json.load(f)

Use Spaces persistent storage (Pro)

For Pro subscribers:

import os
from pathlib import Path

# Data persists between restarts
PERSISTENT_DIR = Path("/data")

def save_data(content):
    with open(PERSISTENT_DIR / "file.txt", "w") as f:
        f.write(content)

Monitoring and logs

View logs

In your Space page:

Click “Logs” tab
See real-time output
Filter by level (info, error, etc.)

Access logs programmatically

from huggingface_hub import HfApi

api = HfApi()
logs = api.get_space_runtime(
    repo_id="username/space-name"
)

print(logs)

Add custom logging

import logging
import gradio as gr

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def process(text):
    logger.info(f"Processing: {text}")
    result = text.upper()
    logger.info(f"Result: {result}")
    return result

demo = gr.Interface(
    fn=process,
    inputs="text",
    outputs="text"
)

demo.launch()

Private Spaces

Restrict access to your Space:

Make Space private

Go to Space settings
Click “Visibility”
Select “Private”
Save

Access private Spaces

from gradio_client import Client

client = Client(
    "username/private-space",
    token="hf_..."
)

result = client.predict("input")

Best practices

Use .gitignore

Don’t upload unnecessary files:

__pycache__/
*.pyc
.env
.DS_Store
venv/

Pin dependencies

Specify exact versions in requirements.txt:

gradio==4.44.0
transformers==4.35.0

Add examples

Help users get started:

demo = gr.Interface(
    fn=process,
    inputs="text",
    outputs="text",
    examples=[
        ["Example 1"],
        ["Example 2"],
    ]
)

Set up error handling

Gracefully handle failures:

def process(text):
    try:
        return model(text)
    except Exception as e:
        raise gr.Error(f"Processing failed: {e}")

Optimize for cold starts

Load models outside the function:

# Load once at startup
model = load_model()

def process(text):
    # Fast inference
    return model(text)

Troubleshooting

Space won’t start

Check logs for errors
Verify requirements.txt dependencies
Ensure app.py runs locally
Check Python version compatibility

Out of memory

Upgrade to higher RAM tier
Reduce model size
Use model quantization
Clear unused variables

Slow performance

Upgrade to GPU hardware
Cache model outputs
Optimize data preprocessing
Use batch processing

Next steps

Docker deployment

Deploy Gradio apps with Docker

Sharing apps

Learn about authentication and embedding

Get Started

Core Concepts

Building Interfaces

Building with Blocks

Chatbots

Advanced Features

Custom Components

Clients & Deployment

Documentation Index

​Overview

​Quick start

​Deployment methods

​Method 1: CLI deployment (recommended)

​Update an existing Space

​Enable GitHub Actions

​Method 2: Web interface

​Method 3: Git workflow

​App structure

​Example app.py

​Example requirements.txt

​README.md metadata

​Hardware options

​CPU (free)

​GPU (paid)

​Change hardware via UI

​Change hardware via CLI

​Sleep timeout

​Environment variables and secrets

​Add secrets via UI

​Add secrets via CLI

​Use secrets in code

​Duplicate Spaces programmatically

​Custom domains

​Persistent storage

​Use Hugging Face Datasets

​Use Spaces persistent storage (Pro)

​Monitoring and logs

​View logs

​Access logs programmatically

​Add custom logging

​Private Spaces

​Make Space private

​Access private Spaces

​Best practices

​Troubleshooting

​Space won’t start

​Out of memory

​Slow performance

​Next steps

Docker deployment

Sharing apps

Build docs developers (and LLMs) love

Overview

Quick start

Deployment methods

Method 1: CLI deployment (recommended)

Update an existing Space

Enable GitHub Actions

Method 2: Web interface

Method 3: Git workflow

App structure

Example app.py

Example requirements.txt

README.md metadata

Hardware options

CPU (free)

GPU (paid)

Change hardware via UI

Change hardware via CLI

Sleep timeout

Environment variables and secrets

Add secrets via UI

Add secrets via CLI

Use secrets in code

Duplicate Spaces programmatically

Custom domains

Persistent storage

Use Hugging Face Datasets

Use Spaces persistent storage (Pro)

Monitoring and logs

View logs

Access logs programmatically

Add custom logging

Private Spaces

Make Space private

Access private Spaces

Best practices

Troubleshooting

Space won’t start

Out of memory

Slow performance

Next steps