Use when deploying Python apps to HuggingFace Spaces. Covers preflight checks, Docker Space setup, CLI deployment, secrets, and monitoring.
Deploy Python applications as Docker-based HuggingFace Spaces via the hf CLI.
Docker SDK is required — ifcopenshell needs system libraries (apt-get).
Run these checks IN ORDER. Stop at the first failure.
pip install -U huggingface_hub
hf version
Requires huggingface_hub >= 1.0.0. The old huggingface-cli is deprecated — use hf.
hf auth whoami
If this fails:
hf auth login (paste token when prompted)~/.cache/huggingface/tokenDuring hf auth login you are prompted "Add token as git credential? (Y/n)" — press Enter to accept. If you skipped it, run:
hf auth login --add-to-git-credential
Without this, git clone and git push to huggingface.co will fail with 401.
git lfs --version
If missing: brew install git-lfs && git lfs install (macOS) or apt install git-lfs (Linux).
Any version is fine — just needs to be installed.
docker --version
Not required for deployment. HF builds Docker images on their infra.
1. Resolve your username → hf auth whoami
2. Create Space repo → hf repo create
3. Clone it locally → git clone
4. Set secrets FIRST → Python SDK (before pushing code!)
5. Add files + push → git push (triggers build on HF)
6. Check status → Python SDK: api.get_space_runtime()
# 1. Get your username (needed for URLs below)
# Note: output format is "user: serJD" — extract last word
HF_USER=$(hf auth whoami | head -1 | awk '{print $NF}')
echo "Deploying as: $HF_USER"
# 2. Create the Space (Docker SDK)
hf repo create my-app --repo-type space --space-sdk docker
# 3. Clone
git clone https://huggingface.co/spaces/$HF_USER/my-app
cd my-app
# 4. Set secrets BEFORE first push (otherwise app crashes on startup)
python3 -c "
from huggingface_hub import HfApi
api = HfApi()
api.add_space_secret('$HF_USER/my-app', key='GEMINI_API_KEY', value='YOUR_KEY')
"
# 5. Add your files (see references/docker-space.md for required files)
# Required: README.md (with frontmatter), Dockerfile, main.py, requirements.txt
# Additional files (src/*.py, data/, etc.) are fine — include whatever you need.
# 6. Push — triggers Docker build on HF (takes 2-5 minutes)
git add -A && git commit -m "initial deploy" && git push
# 7. Check build status (Python SDK — no CLI equivalent)
python3 -c "
from huggingface_hub import HfApi
rt = HfApi().get_space_runtime('$HF_USER/my-app')
print(f'Status: {rt.stage}')
"
# BUILDING → wait. RUNNING → done. ERROR → check logs on HF dashboard.
Your Space URL: