The README front matter is the deployment config

Where the settings live

A Space’s configuration is YAML at the top of README.md. Not a dashboard, not a hidden file: the readme:

---
title: Sentiment Three Ways
colorFrom: indigo
colorTo: blue
sdk: gradio
sdk_version: 5.9.1
app_file: app.py
pinned: false
license: apache-2.0
short_description: Three-way sentiment on English text, not calibrated.
---

Everything below the fence is the readable page.

There is also an emoji field, which takes one character and appears on the gallery card; it is omitted above because nothing depends on it. This is the same pattern as model and dataset cards, and it means the deployment configuration is versioned, diffable and reviewable in a pull request like anything else.

The fields that actually change behaviour

sdk: gradio, streamlit, docker or static. It decides the whole build.

sdk_version: the one people leave off, and the one that causes the mystery. Omit it and the Space builds against whatever the platform currently considers default. Gradio 4 to 5 changed component APIs; a Space that worked in March can fail to start in October with no commit in between. Pin it. If a Space suddenly breaks, this is the first thing to check.

app_file: defaults to app.py. Set it if your entry point is elsewhere.

python_version: pin this too when a dependency is version-sensitive.

models and datasets: lists of repository ids your Space uses. They create links on the Hub in both directions, which is how the “Spaces using this model” counter from module one gets populated. It is metadata, and it is how other people find your work.

hardware and suggested_hardware: the second is a hint to anyone duplicating your Space, so they do not try to run a diffusion model on free CPU and conclude it is broken.

pinned: pins it to your profile.

requirements.txt, and pinning properly

gradio==5.9.1
transformers==4.46.2
torch==2.5.1
sentencepiece==0.2.0

Unpinned dependencies are the second-largest cause of a Space that stops building. Install resolution happens at build time, so a new release of any transitive dependency can break you overnight while your code is untouched.

Three practical notes:

• torch is large. On free CPU hardware, installing the CPU-only build (torch --index-url https://download.pytorch.org/whl/cpu) cuts the image size and the build time substantially, because the default wheel carries CUDA libraries you will never use.
• System packages go in a packages.txt, one per line: ffmpeg, poppler-utils, tesseract-ocr. Audio and PDF Spaces fail without this and the error appears at runtime, not at build.
• pre-requirements.txt exists for the rare case where something must be installed before the main resolution, such as a specific pip version.

Files that do not belong in the repository

A Space is a git repository, so everything in it is public unless the Space itself is private. Weights, datasets and credentials should live in their own repositories and be fetched at startup, not committed here. Use .gitignore, and use the Hub:

from huggingface_hub import snapshot_download
local = snapshot_download("your-name/your-private-model", token=os.environ["HF_TOKEN"])

That keeps the Space small, the build fast, and the weights versioned where they belong.

The readme below the fence matters too

It renders under the app on the Space page. What to put there, in order of how much it helps a visitor:

1. What the thing does, in one sentence, without marketing.
2. What it will do badly: language coverage, length limits, known failure cases.
3. Which model it uses, linked, with the revision if you pinned one.
4. Whether anything a user types is stored. Say “nothing is stored” if nothing is, because visitors cannot tell from the outside and will assume the worst or the best, both wrongly.
5. The licence of your code, which is not automatically the licence of the model inside it.

Do this now

Open the readme of any Space you have built or duplicated and add two things: a pinned sdk_version, and a sentence saying whether user input is stored. Both take a minute. The first prevents a failure; the second is the difference between a demo and something a stranger can trust.