> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/gradio-app/gradio/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://huggingface.co/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:

<Steps>
  <Step title="Create a Hugging Face account">
    Sign up for free at [huggingface.co](https://huggingface.co/join)
  </Step>

  <Step title="Deploy from terminal">
    Run this command in your app directory:

    ```bash theme={null}
    gradio deploy
    ```

    The CLI will:

    * Ask for your Space name
    * Upload all files (respecting `.gitignore`)
    * Launch your app on Spaces
  </Step>

  <Step title="Access your app">
    Your app will be live at:

    ```
    https://huggingface.co/spaces/username/space-name
    ```
  </Step>
</Steps>

## Deployment methods

### Method 1: CLI deployment (recommended)

The fastest way to deploy:

```bash theme={null}
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:

```bash theme={null}
gradio deploy
```

#### Enable GitHub Actions

Automate deployments on every `git push`:

```bash theme={null}
gradio deploy --github-actions
```

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

### Method 2: Web interface

Deploy via drag-and-drop:

<Steps>
  <Step title="Create a new Space">
    Go to [huggingface.co/new-space](https://huggingface.co/new-space)
  </Step>

  <Step title="Choose settings">
    * Pick a name
    * Select "Gradio" as the SDK
    * Choose hardware (CPU or GPU)
  </Step>

  <Step title="Upload files">
    Drag and drop your app folder, or clone via Git
  </Step>
</Steps>

<video autoplay muted loop>
  <source src="https://github.com/gradio-app/gradio/blob/main/guides/assets/hf_demo.mp4?raw=true" type="video/mp4" />
</video>

### Method 3: Git workflow

For version control and collaboration:

```bash theme={null}
# 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

```python theme={null}
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:

```yaml theme={null}
---
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

```python theme={null}
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:

```python theme={null}
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

```python theme={null}
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

```python theme={null}
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()
```

<Warning>
  Never commit secrets to your repository! Always use environment variables.
</Warning>

## Duplicate Spaces programmatically

Create private copies of Spaces for unlimited API usage:

```python theme={null}
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

```python theme={null}
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:

```python theme={null}
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

```python theme={null}
from huggingface_hub import HfApi

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

print(logs)
```

### Add custom logging

```python theme={null}
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

```python theme={null}
from gradio_client import Client

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

result = client.predict("input")
```

## Best practices

<Steps>
  <Step title="Use .gitignore">
    Don't upload unnecessary files:

    ```gitignore theme={null}
    __pycache__/
    *.pyc
    .env
    .DS_Store
    venv/
    ```
  </Step>

  <Step title="Pin dependencies">
    Specify exact versions in `requirements.txt`:

    ```
    gradio==4.44.0
    transformers==4.35.0
    ```
  </Step>

  <Step title="Add examples">
    Help users get started:

    ```python theme={null}
    demo = gr.Interface(
        fn=process,
        inputs="text",
        outputs="text",
        examples=[
            ["Example 1"],
            ["Example 2"],
        ]
    )
    ```
  </Step>

  <Step title="Set up error handling">
    Gracefully handle failures:

    ```python theme={null}
    def process(text):
        try:
            return model(text)
        except Exception as e:
            raise gr.Error(f"Processing failed: {e}")
    ```
  </Step>

  <Step title="Optimize for cold starts">
    Load models outside the function:

    ```python theme={null}
    # Load once at startup
    model = load_model()

    def process(text):
        # Fast inference
        return model(text)
    ```
  </Step>
</Steps>

## 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

<CardGroup cols={2}>
  <Card title="Docker deployment" icon="docker" href="/deployment/docker">
    Deploy Gradio apps with Docker
  </Card>

  <Card title="Sharing apps" icon="share-nodes" href="/deployment/sharing">
    Learn about authentication and embedding
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.