AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

huggingface-zerogpu

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.

Original source
huggingface
License
Apache-2.0
Pinned revision
25910b3d0ba31a2ba102f901cdc9e008c278a69c

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read huggingface--huggingface-zerogpu at revision 25910b3d0ba31a2ba102f901cdc9e008c278a69c, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 5

references/how-quota-works.md

How ZeroGPU duration and quota are checked

Mechanism for duration validation and quota pre-checks. Useful when choosing duration values, debugging illegal duration vs quota exceeded errors, and understanding why the default 60s is pessimistic for short tasks.

For per-tier numerical thresholds (free vs Pro vs Team vs Enterprise quota minutes), the daily quota window length, runs-per-day limits, and pay-as-you-go pricing, see the ZeroGPU docs — those values change over time and are deliberately kept out of this skill.

What duration actually requests

Whatever value is passed to @spaces.GPU(duration=N) (or the default 60s when unspecified) becomes the requested duration the platform checks against. For xlarge, the request is doubled internally:

requested = N * 2 if size == "xlarge" else N

So @spaces.GPU(duration=60, size="xlarge") is internally a 120-second request — both for the tier-max check and the quota pre-check below.

Two distinct error modes

Two failure messages can come back from the scheduler before the call runs:

| Error | Trigger | What helps | |---|---|---| | ZeroGPU illegal duration | requested duration > visitor's tier per-call cap | Lower duration. Sign in / upgrade tier. Waiting does not help. | | ZeroGPU quota exceeded | remaining quota < requested duration, OR runs-per-day cap reached | Wait for the quota window to reset. For Pro / Team / Enterprise, pay-as-you-go credits cover the overflow. |

The error wording for quota exceeded includes the explicit numbers, e.g.:

You have exceeded your Pro ZeroGPU quota
(60s requested vs. 30s left). Try again in 1:23:45.

The comparison is requested vs remaining — not actual run time vs remaining. A 10-second task left at the default 60s requests 60s of quota; once remaining < 60s the call fails even though the actual work would have fit.

Why the default 60s is pessimistic for short tasks

DEFAULT_SCHEDULE_DURATION in the spaces package is 60 seconds. So an undecorated @spaces.GPU (or @spaces.GPU() with no duration=) requests 60s of quota.

For a task that actually takes ~10 seconds:

  • The user's 60s quota gets reserved up front.
  • Once their remaining quota drops below 60s, your Space fails for them — even though they could have run many more 10s tasks if the request matched reality.
  • Your call also ranks lower in the queue than equivalent calls declaring smaller durations.

The fix is to declare the realistic duration explicitly:

@spaces.GPU(duration=15)
def fast_task(...):
    ...

For workloads where runtime depends on inputs, use a callable (per-request estimator):

def estimate_duration(prompt, steps):
    return int(steps * 3.5)

@spaces.GPU(duration=estimate_duration)
def variable_task(prompt, steps):
    ...

This preserves quota for light inputs and reserves more only when needed.

Quota window: 24h fixed from first use

The quota window's TTL is set when the first call of a fresh window lands and counts down unconditionally — it is not a sliding window, not a calendar-day reset, and not extended by subsequent use. A user who runs a call at 14:00 sees their next reset at 14:00 the following day, regardless of how heavily or lightly they use the Space in between.

For exact tier thresholds, runs-per-day caps, and pay-as-you-go billing rates, see the ZeroGPU docs.

Queue priority

The queue is node-level — requests from every Space scheduled on the same physical node compete for that node's GPU slots. Among queued requests, shorter declared duration ranks higher. So tight per-request duration estimates serve two goals at once: they preserve the user's quota and move the request up the queue.