Localized reading guide

huggingface-zerogpuPurpose, usage and source

AI demos and GPU compute with Gradio Spaces and Hugging Face Spaces ZeroGPU. Use when writing or reviewing code that uses @spaces.GPU, configuring python_version or requirements.txt for a ZeroGPU Space, or handling ZeroGPU-specific code constraints — pickle-based process isolation, gr.State semantics across the worker boundary, no torch.compile (use AoTI instead), CUDA wheel-only builds (no nvcc at build or runtime), large vs xlarge sizing, and dynamic duration callables. Make sure to use this skill whenever the user mentions ZeroGPU, @spaces.GPU, or the spaces Python package, or hits ZeroGPU-specific code errors like PicklingError across the worker boundary, illegal duration, or flash-attn wheel-build failures — even when the user does not explicitly ask for ZeroGPU coding guidance. Trigger on import spaces or @spaces.GPU in code.

Source retrieved: 2026-10-29

Source repository: huggingface/skills
SKILL.md: skills/huggingface-zerogpu/SKILL.md
Repository stars: 11,241
Repository updated: 2026-10-30
Categories: Development
Last collected: 2026-10-31 10:38 UTC+08:00

License: Apache-2.0

Source SKILL.md

Workflow excerpts are reading aids, not executable instructions from Codez. No third-party Skill was run to produce this page.

The purpose and workflow passages below are upstream material, organized and translated for reading. They are distinct from the separately labeled Codez editorial analysis.

What this Skill does

How the upstream workflow works

Process Isolation and Pickle

@spaces.GPU-decorated functions run in a separate process managed by the ZeroGPU scheduler. Arguments and return values cross the process boundary via pickle serialization. Only picklable objects can be passed in or returned. Open file handles, database connections, locks, lambdas, and closures over unpicklable state will raise PicklingError. Do NOT return CUDA tensors directly. Unpickling a CUDA tensor in the main process triggers torch.cuda._lazy_init(), which ZeroGPU blocks. Convert to CPU first: return tensor.cpu() or tensor.cpu().numpy(). CPU tensors, numpy arrays, PIL Images, and plain Python objects work fine.

Upstream passage · L169 ↗

Hugging Face ZeroGPU

Rules and patterns for ML demos on Hugging Face Spaces with ZeroGPU hardware. Covers @spaces.GPU, duration and quota tuning, process isolation, the CUDA availability model, concurrency safety, and CUDA build constraints.

Upstream passage · L6 ↗

Scope

This skill is for Gradio SDK Spaces using ZeroGPU hardware. Docker and Static Spaces cannot schedule onto ZeroGPU, and Streamlit apps now run as Docker Spaces — so this skill applies only to Gradio. For general Gradio coding (components, layouts, event listeners), see the huggingface-gradio skill in this repo. The authoritative ZeroGPU docs live at https://huggingface.co/docs/hub/spaces-zerogpu — refer to them for the current backing GPU, runtime version lists, and tier thresholds, all of which change over time.

Upstream passage · L10 ↗

Upstream passage · python ↗

import spaces
import torch
from transformers import pipeline

pipe = pipeline("text-generation", model="...", device="cuda")

@spaces.GPU
def generate(prompt: str) -> str:
    return pipe(prompt, max_new_tokens=100)[0]["generated_text"]

Requirements and setup

Do not pin `spaces` in `requirements.txt`

The Space platform pins its own spaces version. A conflicting pin in requirements.txt causes pip resolution to fail at build time. > Rule: Do not include spaces in requirements.txt.

Upstream passage · L271 ↗

Limits and quality checks

CUDA Build Constraints

HF Spaces builds Docker images in a CPU-only environment. On ZeroGPU, the build phase has no nvcc because the base image is python:3.13 (dedicated-GPU Spaces use nvidia/cuda:*-devel-* and have nvcc at build time). A CUDA-dependent package whose only distribution is sdist — e.g. bare flash-attn — therefore cannot be installed via requirements.txt on ZeroGPU. Only pre-built wheels work. ZeroGPU runtime does have nvcc available, mounted from a CUDA devel image at /cuda-image since 2025-07 (originally added for AoTI support). This is what makes torch.export / AoTI workflows possible inside @spaces.GPU calls.

Upstream passage · L231 ↗

Start with a safe trial

Check the supported host and the repository installation instructions. Keep the Skill directory and its referenced scripts, assets and documentation together; SKILL.md alone may omit dependencies.
Give the agent your real input, desired output and acceptance criteria. Invocation syntax and available tools depend on the host; this site does not assume a universal install command.
Try the source workflow in a disposable project or on a copy. Review operations that change files, remote services or billable resources before allowing them.
Validate the output against the source quality checks and your own requirements. A successful trigger or a high repository Star count does not establish a correct result.

Skill format and directory specification ↗

Read further in the source

Translation and scope

This reading guide selects passages from the pinned upstream SKILL.md. Translation is assisted. It is not a complete manual or a claim of tested compatibility. Read the original and its referenced files before use.

This introduction refers to the pinned version below; current repository activity and collection time are shown separately.

Pinned source: Read the original ↗
Source retrieved: 2026-10-29T09:32:23Z
Source commit: fabc634a893f62ad5c2039830397efa35fa62715
Source SHA-256: 829659aec34224970fe7ed619729fdc7849fc5dd696e2000256c3ee0b517eff7

Back to the full Skill catalog