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/cuda-and-deps.md

CUDA Dependencies on ZeroGPU

Detailed guidance for installing CUDA-dependent packages on ZeroGPU. SKILL.md establishes the bottom line — wheels are the recommended path because the ZeroGPU build phase has no nvcc. This document covers wheel filename tag reading, the kernels-community fallback, and torch-family side-car drift.

When no wheel is available on PyPI

Common workarounds, in preference order:

  1. Pre-built wheel via direct URL. For flash-attn, the upstream project ships a fairly complete matrix at https://github.com/Dao-AILab/flash-attention/releases — check there first and pin the matching wheel URL.
  2. Build the wheel yourself and host it (e.g. on a public HF Hub repo) when no upstream wheel matches the Space environment.
  3. Use a kernels-community kernel (see below) — handles ABI matching for you, no version pinning needed.

Reading a CUDA wheel filename

A wheel filename like

flash_attn-2.8.0.post2+cu12torch2.8cxx11abiFALSE-cp312-cp312-linux_x86_64.whl

encodes four build-time choices:

| Tag | Meaning | |-----|---------| | cu12 | CUDA major version | | torch2.8 | torch major.minor the wheel was compiled against | | cxx11abiFALSE | C++ stdlib ABI choice (TRUE or FALSE) | | cp312-cp312 | CPython version (3.12) |

The wheel's compiled C-extension will ImportError on ABI/symbol mismatches if any of these drift at install time.

If you hand pip a wheel URL without pinning the surrounding environment, pip may resolve torch to a version different from the wheel's build target, and the Space will fail on first import. Therefore:

  • Pin torch==X.Y.Z in requirements.txt to match the wheel's torch2.X tag.
  • Set python_version: in the Space frontmatter to match the cp3XX tag.
  • Check the runtime's cxx11-ABI choice against the wheel; if unsure, try the opposite ABI wheel.

Prefer kernels-community when unsure

If you are not sure about the ZeroGPU runtime's torch / Python / ABI combination, prefer a kernels-community kernel (e.g. kernels-community/flash-attn2) instead of a raw wheel URL. The kernels runtime handles ABI matching on your behalf, so no version pinning is required in your Space.

torch-family side-car drift

torchvision, torchaudio, torchcodec, and similar side-car packages are built against a specific torch major.minor (and CUDA major). On ZeroGPU, the runtime's supported torch list lags behind PyPI, so projects often pin a non-latest torch — and a bare uv add <side-car> can silently resolve to a newer release that targets a different torch / CUDA, producing ABI/import failures even though uv lock succeeded without warnings.

Concretely observed (2026-04) with torch==2.9.1 pinned:

  • torchaudio resolves to 2.11.0, which targets torch 2.11 / CUDA 13. The 2.11.0 release dropped the Requires-Dist: torch==X.Y.Z line that every earlier release had, so uv sees no constraint and picks it.
  • torchcodec resolves to a release targeting torch 2.11. No torchcodec release on PyPI declares a torch dependency at all; the compatibility table lives only in the project README.
  • torchvision happens to resolve correctly because torchvision still declares Requires-Dist: torch==X.Y.Z. Which side-cars are affected changes over time — treat every torch-family package as suspect, not just these.

Verify at add/upgrade time

After any uv add <torch-side-car> or uv lock --upgrade, verify the resolved version targets the same torch major.minor as pinned. Two-step fallback because PyPI metadata is not always sufficient:

  1. Query PyPI for the resolved version's requires_dist:
    curl -s https://pypi.org/pypi/<pkg>/<version>/json \
      | python3 -c "import json,sys,re; rd=json.load(sys.stdin)['info'].get('requires_dist') or []; print('\n'.join(x for x in rd if re.match(r'^torch(?![a-z])', x)) or '(no torch constraint declared)')"
    
    If a torch==X.Y.Z line appears and matches the pinned torch, good. If it appears and does NOT match, the side-car is wrong — pin it down explicitly.
  2. If the query prints (no torch constraint declared), PyPI metadata is silent and cannot be trusted. Fall back to the project's own compatibility table (GitHub README / docs site) — torchcodec, for example, maintains one at https://github.com/pytorch/torchcodec. Pick the side-car version the table maps to the pinned torch major.minor, and pin it explicitly.

Preventive pin

Once the correct side-car version is known, pin it in pyproject.toml alongside torch so uv cannot drift on future uv lock --upgrade. The side-car version numbers for a given torch major.minor change each release; always re-verify, do not copy a mapping from an older project.