Skip to main content
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

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:
HardwarevCPURAMGPU VRAMPrice/hour
T4 Small415 GB16 GB$0.60
T4 Medium830 GB16 GB$0.90
A10G Small415 GB24 GB$1.05
A10G Large1246 GB24 GB$3.15
A100 Large12142 GB40 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