Hugging Face Spaces: Deploy ML Apps in Minutes
This guide walks you through every step of deploying interactive machine learning applications on Hugging Face Spaces. Whether you are building a text classifier demo with Gradio, a data dashboard with Streamlit, or a fully custom environment with Docker, Spaces handles the infrastructure so you can focus on the model. You will learn to create a Space, configure hardware, manage secrets, persist data across restarts, and embed your running app in external websites.
Prerequisites
Before creating your first Space, confirm you have the following tools and accounts in place. Each item below is required for at least one step in this guide.
What Are Spaces?
Hugging Face Spaces are hosted machine learning applications that transform trained models into interactive, shareable web demos or full products. They act as the deployment and application layer of the Hugging Face ecosystem, bridging the gap between research prototypes and real-world generative AI systems.
As of 2026, the platform hosts over 1 million Spaces, making it the largest repository of interactive ML applications in the world. Spaces follow a Git-based CI/CD workflow: every commit to a Space repository triggers an automatic rebuild and deployment, with no manual intervention required.
Supported SDKs
Every Space is built with one of four SDK options. Your choice determines the framework, the default file structure, and the runtime environment.
| SDK | Best For | Entry File |
|---|---|---|
| Gradio | ML-centric interactive demos with component-based interfaces | app.py |
| Streamlit | Data dashboards and analytical applications | app.py |
| Docker | Full control over runtime, dependencies, and system packages | Dockerfile |
| Static HTML | Simple web pages with no server-side processing | index.html |
Creating Your First Space
The fastest path from zero to a running Space takes under five minutes. This section walks through the web UI approach. The Git-based approach follows the same lifecycle but starts from your local terminal.
- ✓Navigate to huggingface.co/new-space
- ✓Choose a Space name and owner (personal or organization)
- ✓Select your SDK (Gradio, Streamlit, Docker, or Static)
- ✓Choose hardware tier (CPU free, or upgrade later)
- ✓Set visibility (public or private)
- ✓Click Create Space and push your application code
Step 1: Create the Repository
Navigate to huggingface.co/new-space. Enter a name for your Space, select the owner account, and choose your SDK. Leave the hardware on the free CPU tier for now. Click Create Space.
Step 2: Add Your Application Code
Clone the newly created repository to your local machine and add your application files. For a Gradio Space, that means an app.py file and a requirements.txt.
git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE
cd YOUR_SPACE
# Add app.py and requirements.txt
git add .
git commit -m "Initial application"
git push
Step 3: Watch the Build
After you push, Hugging Face automatically builds the environment, installs dependencies from requirements.txt, and starts your application. The build logs are visible in the Space's "Logs" tab. When the status indicator turns green, your app is live at https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE.
Continuous deployment: Every subsequent git push triggers an automatic rebuild. There is no separate deploy step, no CI configuration to maintain, and no container registry to manage. This Git-based CI/CD pipeline is built into every Space.
AI Risk Management Template
Identify, assess, and mitigate AI deployment risks
Download Free →Gradio App Walkthrough
Gradio is the most popular SDK for Spaces. It generates a component-based web interface from a Python function with minimal boilerplate. The following example creates a text classification Space using a pre-trained transformer model from the Hugging Face Hub.
import gradio as gr
from transformers import pipeline
classifier = pipeline("sentiment-analysis")
def classify(text):
result = classifier(text)[0]
return f"{result['label']} ({result['score']:.2%})"
demo = gr.Interface(
fn=classify,
inputs=gr.Textbox(label="Enter text"),
outputs=gr.Textbox(label="Sentiment"),
title="Sentiment Classifier",
description="Classify text as positive or negative."
)
demo.launch()
gradio
transformers
torch
Commit both files and push. Hugging Face installs the dependencies, loads the model, and serves the interface. Users interact with your model through the browser without needing Python installed on their machine.
Practitioner note: Gradio is optimized for experimentation, prototyping, and human-in-the-loop interaction. For large-scale consumer applications that require custom authentication, load balancing, or sub-50ms latency, consider dedicated Inference Endpoints or self-hosted infrastructure instead.
Streamlit App Walkthrough
Streamlit is the better choice when your application is data-driven rather than model-driven. Dashboards, exploratory data analysis tools, and chart-heavy applications are where Streamlit excels on Spaces.
import streamlit as st
from datasets import load_dataset
st.title("Dataset Explorer")
st.write("Browse Hugging Face datasets interactively.")
dataset_name = st.text_input(
"Dataset name", value="imdb"
)
if dataset_name:
ds = load_dataset(dataset_name, split="train[:100]")
st.dataframe(ds.to_pandas())
streamlit
datasets
pandas
When you select the Streamlit SDK during Space creation, Hugging Face configures the runtime to serve the Streamlit application automatically. No additional server configuration is needed.
Custom Docker Spaces
Docker Spaces give you complete control over the runtime environment. Use them when your application requires system-level packages, a specific OS image, or a non-Python runtime. Your Space repository needs a Dockerfile at the root.
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 7860
CMD ["python", "app.py"]
Docker Spaces must expose port 7860. The platform routes traffic to this port automatically. Any application that can run in a Docker container can run as a Space, including Node.js backends, Go services, or multi-process applications.
Port requirement: Hugging Face Spaces expects your Docker container to listen on port 7860. If your application uses a different port, remap it in your Dockerfile or application configuration. The platform does not allow custom port mappings.
Hardware Upgrades and GPU Options
Every Space starts on a free CPU instance. When your model requires GPU acceleration for inference, you can upgrade the hardware directly from the Space settings without redeploying your code.
| Tier | Hardware | Cost | Best For |
|---|---|---|---|
| Free CPU | 8 cores, 16GB RAM | $0/hr | Lightweight demos, text tasks, static apps |
| ZeroGPU | Shared on-demand GPU | Included with Pro ($9/mo) | Cost-efficient GPU bursts, up to 10 Spaces |
| GPU Upgrades | A100, H100 | $0 to $23.50/hr | Real-time generation, large models, production demos |
Hardware can be upgraded or downgraded dynamically as performance needs change. There is no need to rebuild or redeploy the application. The platform restarts the Space on the new hardware automatically.
Persistent Storage
By default, a Space is ephemeral. Files written during runtime are lost when the Space restarts, sleeps, or rebuilds. For stateful applications, you can enable persistent storage in the Space settings.
Persistent storage retains data across runs, including:
- Model checkpoints and fine-tuned weights saved during training runs
- Cached datasets and intermediate artifacts that are expensive to recompute
- User-generated content such as uploaded files, feedback logs, or session data
- Application state like configuration files or SQLite databases
Performance benefit: Enabling persistent storage reduces redundant computation and data downloads. A Space that loads a 2GB model on every restart can instead cache the model weights to persistent storage and load from disk in seconds.
Secrets and Configuration
Spaces include a built-in secrets management system that keeps API keys, tokens, and credentials out of your source code. This is essential when your Space calls external APIs, accesses private models, or connects to third-party services.
Environment Variables vs. Secrets
Environment variables are for general runtime configuration such as log levels, feature flags, or non-sensitive settings. They are visible to anyone who can view the Space's settings.
Secrets are encrypted and never exposed in the Space UI, logs, or source code. Use secrets for API keys, database connection strings, and authentication tokens.
import os
api_key = os.environ.get("MY_API_KEY")
# Use the key to call an external service
# Never hardcode credentials in app.py
Both environment variables and secrets are set through the Space's settings page under the "Variables and secrets" tab. The strict separation between code and sensitive information enables safe integration with external services without exposing private credentials. Organizations with AI governance requirements should document which secrets each Space uses and rotate them on a regular schedule.
Embedding Spaces in External Sites
Once your Space is running, you can embed it directly in any website using an HTML iframe. This is useful for adding interactive demos to blog posts, documentation sites, or portfolio pages without hosting the application yourself.
Gradio-based Spaces also support a web component approach using the
Note: Private Spaces cannot be embedded without authentication. If you need to embed a demo on a public website, the Space must be set to public visibility.
Limitations and Caveats
Spaces handles infrastructure complexity for you, but the platform has constraints worth understanding before you commit to a production workflow.
Troubleshooting Common Issues
Most Space deployment issues fall into a small number of categories. The troubleshooting accordion below covers the problems practitioners encounter most frequently.
Video Resources
Go Deeper
Resources from across Tech Jacks Solutions
FREEAI Risk Management Template
Identify, assess, and mitigate AI deployment risks
EU AI Act Guide
Check your compliance obligations under the EU AI Act
FREEAI Bias Assessment
Evaluate bias risks before deploying any AI system
What Is Agentic AI?
Understand the architecture behind autonomous AI agents
AI Career Paths
Explore roles that work with these tools daily