huggingface-zerogpu

Implement and debug Hugging Face Spaces ZeroGPU code using the @spaces.GPU decorator.

507|40|Updated Apr 26, 2026
One-click install
npx skills add https://github.com/waybarrios/opencode-power-pack --skill huggingface-zerogpu-waybarrios
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: huggingface-zerogpu
Source: https://github.com/waybarrios/opencode-power-pack/tree/main/skills/huggingface-zerogpu
Command: npx skills add https://github.com/waybarrios/opencode-power-pack --skill huggingface-zerogpu-waybarrios

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires spaces, torch, gradio, and includes references (resource) components.

What problem does it solve? ZeroGPU Spaces behave differently from ordinary GPU environments: the GPU is only attached inside decorated functions, handlers run concurrently by default, quota is pre-checked against declared duration, and CUDA builds lack nvcc. This Skill prevents the subtle failures—quota rejections, pickle errors, hangs, and build breakage—that come from treating ZeroGPU like a normal GPU. ## Core Features & Use Cases - Correct @spaces.GPU usage: Covers module-scope model loading, duration and size tuning, dynamic duration callables, and why torch.compile must be replaced with AoTI. - Isolation and concurrency safety: Explains pickle boundaries, gr.State copy semantics, the ban on returning CUDA tensors, and rules against mutable globals and fixed file paths. - Dependency and build constraints: Details wheel-only CUDA installs, wheel filename tag reading, torch side-car pinning, and the python_version frontmatter requirement. - Use Case: You are building a Gradio image-generation demo on ZeroGPU and users hit "quota exceeded" after a few runs. This Skill shows you to declare a realistic duration (e.g. 15s instead of the 60s default) so requests stop being rejected prematurely. ## Quick Start Ask the assistant to review my ZeroGPU Gradio app for correct @spaces.GPU usage, duration settings, and concurrency safety.

Frequently Asked Questions about huggingface-zerogpu

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I use @spaces.GPU on Hugging Face ZeroGPU?▼

Load models at module scope with device="cuda", then decorate inference functions with @spaces.GPU. Real GPU access exists only inside decorated calls; the decorator is a no-op off ZeroGPU, so the same code runs locally unchanged.

Why does ZeroGPU say quota exceeded when my task is fast?▼

The platform pre-checks your declared duration against remaining quota, not actual runtime. The default is 60s, so once a user's remaining quota drops below 60s the call fails. Declare a realistic smaller duration like @spaces.GPU(duration=15).

Can I return CUDA tensors from a @spaces.GPU function?▼

No. Returning CUDA tensors hangs the call because unpickling in the main process triggers torch.cuda._lazy_init, which ZeroGPU blocks. Convert outputs to CPU first with .cpu() or .cpu().numpy() before returning.

How do I install flash-attn on a ZeroGPU Space?▼

ZeroGPU builds have no nvcc, so source distributions cannot compile. Install a pre-built wheel via direct URL from the upstream releases page, pin torch to match the wheel's torch tag, or use a kernels-community kernel that handles ABI matching.

Does torch.compile work on ZeroGPU?▼

No, torch.compile is not supported on ZeroGPU. Use PyTorch ahead-of-time compilation (AoTI) with torch 2.8 or later instead, which works because the ZeroGPU runtime mounts nvcc from a CUDA devel image.

Should I wrap import spaces in try/except for local development?▼

No. The spaces package is already a no-op off ZeroGPU: @spaces.GPU returns the function unchanged and heavyweight behavior is gated on the SPACES_ZERO_GPU environment variable. A fallback shim drifts from the real API and hides the dependency.