Hugging Face Spaces

Deploy Gradio apps to Hugging Face Spaces for free permanent hosting

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:

1. Create a Hugging Face account

   Sign up for free at huggingface.co

2. 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
3. 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:

1. Create a new Space

   Go to huggingface.co/new-space

2. Choose settings

   • Pick a name
   • Select “Gradio” as the SDK
   • Choose hardware (CPU or GPU)
3. 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

1. Go to your Space settings
2. Click “Hardware”
3. Select new tier
4. 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

1. Go to Space settings
2. Click “Variables and secrets”
3. Add name and value
4. 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:

1. Go to Space settings
2. Click “Domains”
3. Add your domain (e.g., demo.mycompany.com)
4. Update DNS records as shown
5. 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:

1. Click “Logs” tab
2. See real-time output
3. 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

1. Go to Space settings
2. Click “Visibility”
3. Select “Private”
4. Save

Access private Spaces

from gradio_client import Client

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

result = client.predict("input")

Best practices

1. Use .gitignore

   Don’t upload unnecessary files:

   __pycache__/
   *.pyc
   .env
   .DS_Store
   venv/
   
2. Pin dependencies

   Specify exact versions in requirements.txt:

   gradio==4.44.0
   transformers==4.35.0
   
3. Add examples

   Help users get started:

   demo = gr.Interface(
       fn=process,
       inputs="text",
       outputs="text",
       examples=[
           ["Example 1"],
           ["Example 2"],
       ]
   )
   
4. 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}")
   
5. 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