Creating a Hugging Face Space Beginner

In this lesson, you will create your first Hugging Face Space, set up Git integration, configure your dependencies, and deploy a working application. The entire process takes just a few minutes.

Step 1: Create a Space via the Web UI

  1. Go to huggingface.co/spaces

    Sign in to your Hugging Face account (create one for free if you don't have one).

  2. Click "Create new Space"

    Choose a name for your Space, select the SDK (Gradio, Streamlit, or Docker), and set visibility (public or private).

  3. Select hardware

    Choose "CPU Basic (Free)" to start. You can upgrade to GPU later if needed.

Step 2: Clone and Set Up Locally

Terminal
# Clone your Space
git clone https://huggingface.co/spaces/YOUR_USERNAME/my-first-space
cd my-first-space

# You'll see a README.md with Space metadata
cat README.md

Step 3: Understanding the README Metadata

Every Space has a README.md with YAML front matter that configures the Space:

YAML (README.md)
---
title: My First Space
emoji: 🚀
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 4.44.0
app_file: app.py
pinned: false
license: mit
---

Step 4: Create requirements.txt

List your Python dependencies:

requirements.txt
gradio==4.44.0
transformers
torch
Pillow

Step 5: Create app.py

Build a simple image classification app:

Python (app.py)
import gradio as gr
from transformers import pipeline

# Load a pre-trained model from Hugging Face Hub
classifier = pipeline("image-classification", model="google/vit-base-patch16-224")

def classify_image(image):
    results = classifier(image)
    return {r["label"]: r["score"] for r in results}

demo = gr.Interface(
    fn=classify_image,
    inputs=gr.Image(type="pil"),
    outputs=gr.Label(num_top_classes=5),
    title="Image Classifier",
    description="Upload an image to classify it using ViT."
)

demo.launch()

Step 6: Deploy

Terminal
# Add, commit, and push
git add app.py requirements.txt
git commit -m "Add image classification app"
git push

# Your app will be live at:
# https://huggingface.co/spaces/YOUR_USERNAME/my-first-space

Alternative: Using the huggingface_hub Library

Python
from huggingface_hub import HfApi

api = HfApi()

# Create a new Space programmatically
api.create_repo(
    repo_id="my-space",
    repo_type="space",
    space_sdk="gradio",
    private=False
)

# Upload files
api.upload_file(
    path_or_fileobj="app.py",
    path_in_repo="app.py",
    repo_id="YOUR_USERNAME/my-space",
    repo_type="space"
)
Pro Tip: Use the huggingface-cli to manage authentication. Run huggingface-cli login and paste your access token to authenticate Git operations with Hugging Face.

Space Created!

Your first Space is live. Next, dive deeper into building rich Gradio applications on Spaces.

Next: Gradio Spaces →

Ready to Go Deeper?

Live instructor-led courses from our partners. Affiliate disclosure.