DEV Community

KAMAL KISHOR
KAMAL KISHOR

Posted on

How to Upload Your Project to Hugging Face Spaces: A Beginner's Step-by-Step Guide

#programming #beginners #ai #machinelearning

Hugging Face Spaces is a free platform to deploy and share machine learning apps using Python tools like Gradio, Streamlit, or FastAPI. In this guide, we’ll walk you through the two main methods for uploading your app:
🔐 HTTPS (using access token) — easy and recommended for most users
🔑 SSH (for advanced users) — useful for devs who prefer key-based workflows

🧱 Prerequisites

✅ Method 1: Upload via HTTPS (Access Token) – Recommended

Step 1: Create a New Space

  1. Go to Hugging Face Spaces
  2. Click “Create new Space”
  3. Choose:
  • Space Name
  • SDK: Gradio, Streamlit, etc.
  • Visibility: Public or private
    1. Click Create Space. This gives you a Git URL like: https://huggingface.co/spaces/your-username/your-space-name

Step 2: Generate Access Token

  1. Go to Settings → Access Tokens
  2. Click “New token”
  3. Choose:
  • Name: e.g., space-push
  • Role: Write
    1. Copy the token (you’ll need it in Step 3)

Step 3: Push Your Project Using the Token

In your terminal:

cd your-project-folder
git init
git remote add origin https://<your-username>:<your-token>@huggingface.co/spaces/<your-username>/<your-space-name>
git add .
git commit -m "Initial commit"
git push -u origin main
Enter fullscreen mode Exit fullscreen mode

Replace:

  • <your-username>: Hugging Face username
  • <your-token>: The access token you just copied
  • <your-space-name>: The name of the Space you created

✔️ That’s it! Your app will deploy automatically.

🔐 Method 2: Upload via SSH (Advanced)

SSH lets you push without typing a token each time, but setup is longer.

Step 1: Generate SSH Key (if you don't have one) 

ssh-keygen -t rsa -b 4096 -C "your-email@example.com"
Enter fullscreen mode Exit fullscreen mode
  • Save it as huggingFace_key or just press Enter for default path
  • You’ll get two files: huggingFace_key and huggingFace_key.pub

Step 2: Add the Public Key to Hugging Face

  1. Go to Settings → SSH Keys
  2. Click “New SSH Key”
  3. Paste the content of huggingFace_key.pub 
clip < huggingFace_key.pub  # On Windows
cat huggingFace_key.pub     # On Mac/Linux
Enter fullscreen mode Exit fullscreen mode
  1. Give it a name like laptop-ssh

Step 3: Configure SSH Remote

  1. Set your remote URL: 
git remote set-url origin git@huggingface.co:spaces/your-username/your-space-name.git
Enter fullscreen mode Exit fullscreen mode
  1. Push your code: 
git add .
git commit -m "Initial SSH push"
git push
Enter fullscreen mode Exit fullscreen mode

🚧 SSH Troubleshooting

  • If you see ssh: connect to host huggingface.co port 22: Connection timed out, your network may block port 22.

    • 🔁 Try switching to HTTPS method above
    • 🌐 Try another network (e.g., mobile hotspot)

🧪 Sample Project Structure

Here’s a simple app that converts temperature using Gradio:

mcp-temperature-converter/
├── app.py
├── requirements.txt
└── README.md
Enter fullscreen mode Exit fullscreen mode

app.py

import gradio as gr

def convert(temp_f):
    return (float(temp_f) - 32) * 5/9

gr.Interface(fn=convert, inputs="text", outputs="text", title="F to C Converter").launch()
Enter fullscreen mode Exit fullscreen mode

requirements.txt

gradio
Enter fullscreen mode Exit fullscreen mode

🔁 Updating Your App

After making changes locally, just run:

git add .
git commit -m "Update app"
git push
Enter fullscreen mode Exit fullscreen mode

Your Hugging Face Space will automatically redeploy with the latest code.

🎉 You're Live!

You now have a public (or private) URL to share your deployed AI tool with others.

Top comments (0)