Hugging Face Spaces: what they are and how to use them ?

#Hugging Face Spaces: what exactly is it?

A Space is a small web app hosted by Hugging Face. Technically, it's a git repository, like the model and dataset repos on the Hub: it contains the app code, a dependencies file and a README whose YAML header describes the configuration. Every time a commit is pushed to this repo, Hugging Face rebuilds and restarts the app. Visitors see only a page with fields, buttons and a result.

If you're new to Hugging Face, remember how it differs from a model page: a model page contains files (weights, tokenizer, configuration) that you download; a Space runs code on a server to show you what the model can do. The guide « Hugging Face: c'est quoi, et comment s'en servir? » covers the Hub in general; here, we only cover Spaces.

The official documentation offers three types of Spaces, called SDKs, which you choose when creating one:

Gradio

The most common case. Gradio is a Python library that generates a web interface from a function: a text box as input, an image as output, and so on. Most LLM and image model demos are Gradio Spaces.

Docker

The Space is built from a Dockerfile, so it can run any web application: a full chat interface, an API server, or a tool written in a language other than Python.

Static HTML

A plain HTML, CSS, and JavaScript page, with no compute server. Useful for documentation, a visualization, or a demo that runs entirely in the browser.

Each Space has an address on the Hub, in the form huggingface.co/spaces/owner/name, and a direct application address, in the form owner-name.hf.space. Spaces can be public (code and app visible to everyone), protected (private code, accessible app), or private (restricted to the owner and their collaborators).

#Step 1: Use a demo in the browser

In most cases, you don't need an account to try a Space. The Spaces home page (huggingface.co/spaces) lets you search by keyword or task and sort by trending or by number of “likes.” Many model pages also list, in the right-hand column, the Spaces that use that model.

1. 01
   Find the right Space

   Favor Spaces published by the model's developer (the organization's official account) or ones with a large following. A recent Space from an unknown account may work perfectly well, but you don't know what its code does with the data you send.
2. 02
   Read the displayed status

   At the top of the page, a badge shows the status: running (Running), building (Building), sleeping (Sleeping), paused, or error. A sleeping Space wakes up when someone visits it, which can take a moment while the app restarts.
3. 03
   Send a request

   Fill in the fields and submit. On a Space that shares a GPU among all visitors, a queue may appear before processing starts.
4. 04
   Check what you're testing

   Open the Files tab to read the main file (often app.py) and the README. They show which model is loaded, at what precision (FP16, 4-bit quantization…), and with which parameters. A demo isn't always the full version of the advertised model.

#Step 2: Call a Gradio Space via API

A Gradio Space isn't just a web page: it also exposes an API. The “Use via API” link at the bottom of the app shows the available endpoints and code examples. In Python, the official gradio_client library lets you call a Space like a function, which is handy for testing a model on a batch of examples without clicking through them by hand.

pip install gradio_client

from gradio_client import Client

# Remplacez par l'identifiant du Space (propriétaire/nom)
client = Client("proprietaire/nom-du-space")

# Affiche les points d'entrée et leurs paramètres
client.view_api()

Once you know the parameters, the client.predict() method sends a request with the expected arguments and an api_name given by view_api(). The Space's quotas and queues apply to these calls just as they do to browser visits: this isn't a solution for processing large volumes. For a private Space, or to be identified (and use your account's ZeroGPU quota), pass a Hugging Face access token to Client().

#Step 3: Duplicate a Space

Duplicating a Space creates a full copy in your account. This is useful when you want to start from an existing demo and modify it, or have your own instance without sharing the queue with every visitor. You do this from the three-dot menu at the top right of the page, using the "Duplicate this Space" option.

1. 01
   Choose the owner and name

   The copy can go to your personal account or to an organization where you have write access.
2. 02
   Set visibility

   The copy is private by default. Keep it private if you plan to process your own data with it.
3. 03
   Choose the hardware

   By default, the copy runs on CPU Basic. You can pick a paid GPU at that point or later in Settings.
4. 04
   Enter the secrets

   Public variables from the original Space are copied automatically. Secrets (tokens, API keys) never are: the interface warns you if you need to provide them. Without them, the app may start and then fail on the first request.

Hardware beyond CPU Basic is billed by the hour. For example, the documentation lists $0.40 per hour for a NVIDIA T4 small, as of October 26, 2026; the full, up-to-date price list is on Hugging Face's pricing page. A paid Space can be paused from its settings: time spent paused isn't billed.

#Step 4: Run a Hugging Face Space locally

Since the code of a public Space is readable and clonable, you can run it on your own machine. There are two methods: pull the Docker image built by Hugging Face, or clone the repository and launch the app yourself.

#Method A: The Space's Docker image

The documentation states that most Spaces can be run with Docker. The “Run with Docker” button, in the menu at the top right of the Space page, shows the exact command to copy. It usually looks like this, with the image hosted on the registry.hf.space registry:

docker run -it -p 7860:7860 --platform=linux/amd64 \
  registry.hf.space/proprietaire-nom-du-space:latest python app.py

Always copy the command provided by the button rather than reconstructing it: the image name, the startup command, and any variables (the -e option, for example for an HF_TOKEN token) depend on the Space. Some Spaces require you to log in to the registry with your Hugging Face username and an access token as the password:

docker login registry.hf.space

For a container to use a NVIDIA card, Docker needs the NVIDIA Container Toolkit on the host machine, and you must add the --gpus all option to the docker run command. The images are built for the x86_64 architecture (linux/amd64): on an Apple Silicon Mac, they run under emulation, with no access to the Mac's GPU. In that case, method B is usually a better fit.

#Method B: Clone the repository and run the app

The Space menu also offers "Clone repository," over HTTPS or SSH. For a Gradio Space, the usual sequence is to clone, create an isolated Python environment, install the dependencies listed in requirements.txt, and then run the main file:

git clone https://huggingface.co/spaces/proprietaire/nom-du-space
cd nom-du-space
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install gradio
python app.py

Gradio then displays the interface's local address, http://127.0.0.1:7860 by default. A few things to check before launching:

README header

The sdk_version, app_file, and sometimes python_version keys indicate the Gradio version, the file to run, and the Python version used online. Installing the same Gradio version (pip install "gradio==X.Y.Z") avoids many interface errors.

Large files

A Space can contain large files stored via the Hub's storage system. If files show up as small text pointers after cloning, install the git extension recommended by Hugging Face (git-xet or Git LFS) and run the download again.

@spaces.GPU decorator

ZeroGPU Spaces import the spaces module and decorate their functions with @spaces.GPU. The documentation states that this decorator has no effect outside ZeroGPU: you just need to install the spaces package (pip install spaces) for the code to run on your own GPU.

Secrets

If the code reads environment variables (os.getenv), set them in your terminal before running app.py. A gated model requires a Hugging Face token tied to an account that has accepted the license.

For a Docker Space, the cloned repository contains a Dockerfile: docker build followed by docker run is all you need, publishing the port declared by app_port in the README (7860 by default).

#Hugging Face Spaces limitations: compute and privacy

A Space is perfect for a first impression. For regular use, its limitations quickly become apparent. The ones below come from the official documentation consulted on October 26, 2026.

Modest free hardware

The default hardware, CPU Basic, provides 2 vCPUs, 16 GB of RAM, and 50 GB of disk, with no GPU. An LLM with several billion parameters runs slowly on it, if it fits in memory at all.

Non-persistent disk

The 50 GB disk is wiped on restart. Uploaded or generated files are not kept unless the owner has configured persistent storage.

Sleep mode

On free hardware, an unused Space goes to sleep after a while and has to restart on the next visit. The owner can also pause it, or even delete it: a demo available today may be gone tomorrow.

ZeroGPU quotas

Daily GPU time is limited per account (see above), and a request is limited by default to 60 seconds of GPU time, unless the author sets a longer duration. The quota resets 24 hours after first use.

Restricted network

A Space can only make outbound connections on ports 80, 443, and 8080. An app that needs to reach a service on another port won't work as is.

On privacy, the rule is simple: anything you enter in a Space is sent to a server running someone else's code. That code can log requests, forward them to a third-party API, or keep uploaded files for the duration of the session. On a public Space, you can check this by reading app.py; on a protected Space, the code isn't visible. So never paste client documents, personal data, proprietary code, or credentials into a demo.

#When to prefer running locally

The smart approach is to use Spaces to decide, then switch to local to do the actual work. A few situations where local clearly wins:

Sensitive data

Contracts, medical records, company code: with a local model, nothing leaves your machine.

Daily or high-volume use

ZeroGPU quotas and queues make a Space unsuitable for sustained use. Locally, the only limit is your hardware.

Need for stability

A Space can switch models or versions, or disappear. A downloaded, pinned model gives reproducible results.

Integrating with your tools

Ollama exposes a local API at http://localhost:11434 that Open WebUI, scripts or automations can use, without relying on a remote service.

For an LLM, running it locally doesn't necessarily mean cloning the Space. Many demos load the full model in safetensors format, in FP16: the weights of a 7B model then take up about 14 GB, more than most consumer cards can handle. The quantized version of the same model in GGUF format, in Q4_K_M, needs about 5 GB of VRAM and runs on a 12 GB RTX 3060. The simplest approach is often to note the name of the model the Space uses, then look for its GGUF version on the Hub and import it into Ollama.

3B in Q4

about 2 GB of VRAM

7B in Q4

about 5 GB

14B in Q4

about 9 GB (RTX 4070 12 GB)

32B in Q4

about 19 GB (RTX 4090 24 GB or Mac M4 Pro with 24 to 48 GB of unified memory)

70B in Q4

about 40 GB

#Troubleshooting

“Runtime error” on the page

The Space crashed on startup. The Logs tab, when accessible, shows the cause. If it's someone else's Space, all you can do is wait, look for another Space, or report the issue in the Community tab.

GPU quota exceeded message

Your daily ZeroGPU quota is used up. Sign in if you haven't already, wait for the reset, or run the model locally.

import après pip install error

Your Gradio version or a dependency version differs from the Space's. Match the sdk_version and python_version from the README, in a fresh virtual environment.

CUDA not found locally

The code expects a NVIDIA GPU. Check that PyTorch was installed with CUDA support, or adapt the code to use the CPU (or mps on a Mac), at the cost of slower execution.

Docker image rejected or not found

Log in to the registry with docker login registry.hf.space, then check that the image name matches the one given by the "Run with Docker" button.

#Go further

This guide covers Spaces. To understand the Hub as a whole, tell file formats apart, or move from a demo to a model running on your own machine, these guides pick up from here.