Deploy and maintain ML applications on Hugging Face Spaces

This guide walks through building, deploying, verifying, and maintaining an application hosted as a Hugging Face Space, which is a Git repository. It helps choose Gradio, Docker, or Static SDKs; select hardware; reuse an existing demo; configure the repository; iterate against the hosted environment; and diagnose build, startup, inference, and client failures. It also covers ZeroGPU, dedicated hardware, inference providers, community GPU grants, and persistent Buckets.

Use it when creating a Space, adapting a demo, choosing an execution model, or troubleshooting a deployment. Gradio fits Python interfaces and supports ZeroGPU; Docker is for arbitrary container stacks but does not support ZeroGPU; Static suits plain HTML, browser-side ML, and built frontends. Check for an existing Space before creating another. Consider an inference provider when the model should not be hosted in the Space. Free cpu-basic, zero-a10g, and Static options differ from paid dedicated hardware; verify current availability, quotas, and costs before choosing. Check hf installation and authentication first, and use account canPay and isPro information when evaluating hardware access.

Inputs include the workload and model, an existing repository or demo, SDK, visibility, hardware and payment eligibility, dependencies, startup duration, and persistence needs. Creation configures a Space repository and its README frontmatter, app files, and requirements. Frontmatter includes title, emoji, color pair, SDK, SDK version, app file, short description, Python version, and startup timeout; for a built Static frontend it can name the build command and built entry point. Keep secret values in secret settings, not visitor-visible environment variables.

For ZeroGPU, import spaces before Torch or other CUDA-touching imports, load the model at module scope and move it to CUDA eagerly, then decorate the function Gradio binds with @spaces.GPU. Estimate realistic worst-case duration; input-dependent work can use a callable duration. The guide covers memory sizing (large vs xlarge), NF4/int8 quantization, torchao, attention backends, concurrency, process isolation and pickle behavior, gr.State across worker boundaries, generators, compilation, allocator settings, example caching, and real-time sessions. These details matter because the GPU worker boundary affects state and serialization, while quota and memory limits can fail at inference time.

Dependency guidance distinguishes platform-managed packages from app dependencies: do not pin gradio, spaces, or huggingface_hub; include packages such as torchvision or torchaudio when used. ZeroGPU supports a limited set of Torch versions, so leave Torch unpinned unless a dependency requires a pin. Check Torch-family side-car compatibility and use the documented prebuilt Blackwell CUDA wheels when applicable; do not pin xformers or spaces casually. Pin Python to match a selected wheel. The guide also explains wheel filenames and what to do when a required wheel is unavailable.

The Gradio reference covers themes, layouts, gr.Markdown, cached gr.Examples, streaming, UX controls, custom HTML, gr.Server frontends, and slow startup for large models. For provider-backed inference, choose whether the Space creator or visitor pays; visitor-paid public demos need the corresponding flow. Do not wrap a provider call in @spaces.GPU, since the provider runs the model remotely. Community GPU grants are another route when a use case needs hardware, with separate guidance on eligibility and when not to suggest one.

A source command for following runtime logs is:

hf spaces logs <id> --follow

After pushing a candidate, use the Space itself as the test environment. Select the least expensive update path: hot reload for Python changes, hf upload for code files hot reload cannot handle, and a full rebuild when requirements, Dockerfile, or README frontmatter changes. The debugging ladder documents hot reload limitations, including poisoned state and lagging runtime hashes, before heavier approaches such as dev mode and SSH.

Verification proceeds from runtime and hardware status to clean post-boot logs, a real API call, and inspection of both output bytes and logs. Discover Gradio endpoints with Client.view_api() rather than guessing; allow long inference timeouts where needed. A RUNNING stage or HTTP 200 is not sufficient: check that returned files have the expected format and dimensions and that logs show no CPU fallback, dtype downgrade, or missing optional dependency. The guide includes smoke-test patterns for streaming, OAuth-gated Spaces, and custom gr.Server routes.

Spaces are stateless and /data is cleared on restart. Attach a Bucket when uploads, generations, logs, or other user data must persist. The documented pattern separates durable writes from fast reads; avoid treating a Bucket as a cache for large model weights and consider redirects and write access carefully. Buckets are paid storage, so confirm the user can pay before creating one. The security reference discusses public bucket URLs and safe access.

For failures, inspect the first build or runtime error, look up the exact symptom in the known-errors reference, then use the cheapest applicable debugging step. The catalog groups configuration and dependency-resolution errors, import and CUDA initialization failures, ZeroGPU duration/quota/memory issues, pickle and attention-kernel errors, and Gradio client timeout or endpoint problems. It also describes sparse logs, a running Space returning 404, and unhealthy startup. Use dev mode and SSH only as a last resort, after its prerequisites, container smoke test, and persistence steps are understood.

The platform and tooling touchpoints are Hugging Face Hub/Spaces, hf CLI, Git, Gradio and gradio_client, Docker, Static frontends, ZeroGPU, dedicated hardware, inference providers, and Buckets. Reference files divide operational details across grants, ZeroGPU, provider billing, requirements and CUDA wheels, Gradio components, debugging and smoke tests, Buckets, and known errors. Read the focused reference for the chosen path instead of treating all hardware and deployment options as interchangeable.

Developers and teams publishing machine-learning demos, interactive reports, API proxies, or web apps can use the guide to choose a hosting approach and maintain a working Space.