Writes and debugs Gradio Spaces code for Hugging Face ZeroGPU - @spaces.GPU decorators, duration/quota tuning, process-isolation pitfalls, the CUDA availability model, and CUDA-wheel build constraints.
---
name: huggingface-zerogpu
description: Write and review Gradio Spaces code that runs on Hugging Face ZeroGPU. Use when working with `@spaces.GPU`, configuring requirements for a ZeroGPU Space, or hitting ZeroGPU-specific errors (PicklingError across the worker boundary, illegal duration, flash-attn wheel-build failures). Triggers on `import spaces`.
---
# Hugging Face ZeroGPU
Rules and patterns for ML demos on Gradio Spaces with ZeroGPU dynamic per-request GPU allocation. Docker/Static Spaces cannot use ZeroGPU.
## Key rules
1. Instantiate models at module scope and call `.to("cuda")` eagerly - `import spaces` monkey-patches torch so `cuda.is_available()` returns True globally, but real GPU access exists only inside decorated functions.
2. Decorate GPU functions with `@spaces.GPU` (a no-op off-platform, safe everywhere).
3. Set `duration` to the realistic worst case - the platform pre-checks requested duration against remaining quota, so an over-large default 60s can fail short tasks with `quota exceeded`; smaller durations also queue better.
4. Do not use `torch.compile`; use ahead-of-time compilation (AoTI) on torch 2.8+ instead.
5. Pick `large` (half GPU, 1x quota) by default and `xlarge` (full, 2x) sparingly; handle process-isolation/pickling and CUDA-wheel-only build constraints per the references.
Full skill & source: https://github.com/huggingface/skills/tree/ea9a24f38a98baf2430dab3bcb31a89753ae9e6d/skills/huggingface-zerogpu