Nunchaku

---
name: nunchaku
description: "Route and operate the Nunchaku repo skill for CUDA-accelerated
  4-bit Diffusers image-generation workflows, quantized transformers,
  LoRA/adapters, and performance controls."
metadata:
  disco-role: operating
disable-model-invocation: true
license: Apache 2.0
---

# nunchaku

Use this repo skill when a task involves the `nunchaku` Python package: loading Nunchaku quantized `.safetensors`/`.sft` assets, replacing Diffusers transformer/UNet components, choosing INT4 vs FP4 assets, debugging CUDA/build/runtime issues, composing FLUX LoRAs, or adapting Nunchaku examples/tests into bounded user workflows.

Do **not** use this skill for generic Diffusers work that does not use Nunchaku, CPU-only image generation, unsupported GPU architectures, training new models, or Qwen custom LoRA workflows. Qwen custom LoRA support is documented as under development.

## First steps

1. If Nunchaku is not installed, prefer a prebuilt wheel that matches the user's Python, PyTorch, CUDA, OS, and GPU architecture; use `references/installation-build-runtime.md` for source builds and compatibility repairs.
2. Check installation and backend with `scripts/inspect_nunchaku_install.py --device cuda:0 --pretty` or the `performance-and-memory` checker before promising CUDA-specific behavior.
3. Identify the model family and route to the smallest matching sub-skill.
4. Require explicit model assets or Hugging Face IDs from the task. Do not assume source-checkout example defaults are available.
5. Treat repo-native tests/examples as verification candidates unless they have been run in the current task.
6. If model downloads or private gated assets are required, ask for credentials/cache policy or use local paths.

## Route by task

| User task | Load |
| --- | --- |
| FLUX.1-dev/schnell/krea, FLUX Kontext, FLUX tools, FLUX v2 transformer replacement | `sub-skills/flux-pipelines/SKILL.md` |
| Qwen-Image, Qwen-Image-Edit, Qwen Lightning, Qwen 2509, Qwen ControlNet/offload | `sub-skills/qwen-image-workflows/SKILL.md` |
| Sana, Sana PAG, Z-Image, SDXL, SDXL-Turbo | `sub-skills/sana-zimage-sdxl/SKILL.md` |
| Cache, offload, FP16 attention, quantized T5 encoder, CUDA architecture/precision checks, speed/memory planning | `sub-skills/performance-and-memory/SKILL.md` |
| FLUX LoRA loading/composition/conversion, safetensor merge, IP-Adapter, PuLID | `sub-skills/lora-and-adapters/SKILL.md` |

## Core package facts

- Public root exports include `NunchakuFluxTransformer2dModel`, `NunchakuFluxTransformer2DModelV2`, `NunchakuQwenImageTransformer2DModel`, `NunchakuSanaTransformer2DModel`, `NunchakuZImageTransformer2DModel`, and `NunchakuT5EncoderModel`.
- Important non-root helpers live under package modules: `nunchaku.caching.diffusers_adapters.apply_cache_on_pipe`, `nunchaku.models.ip_adapter.diffusers_adapters.apply_IPA_on_pipe`, `nunchaku.lora.flux.compose.compose_lora`, `nunchaku.lora.flux.nunchaku_converter.to_nunchaku`, and `nunchaku.merge_safetensors.merge_safetensors`.
- Nunchaku quantized inference is a CUDA-backed workflow. CPU-only is not a full substitute for selected package capabilities.
- Precision is architecture-sensitive: current guidance is INT4 for Turing/Ampere/Ada and FP4 for Blackwell-class GPUs. Use `nunchaku.utils.get_precision()` when possible.
- Build/source installs require compatible Python, PyTorch, CUDA, compiler, and initialized submodules; prefer a prebuilt wheel when the task is only runtime usage.

## Root references and scripts

- `references/repo-provenance.md` — source commit, package version, evidence paths, and staleness signals.
- `references/repo-routing-metadata.json` — structured router metadata for managed repo-skill import tooling.
- `references/api-and-entrypoints.md` — public API, helper functions, CLI/module entry points, and native candidate map.
- `references/installation-build-runtime.md` — supported Python/CUDA/GPU/PyTorch combinations and source-build troubleshooting.
- `references/troubleshooting.md` — cross-cutting install/import, asset, backend, and workflow failure diagnoses.
- `scripts/inspect_nunchaku_install.py` — safe JSON probe for the current Python environment.

## Safety and verification boundaries

- Do not copy local checkout paths, private environment names, or construction logs into user code.
- Do not run long image generation, benchmark, or model-download workflows unless the user authorizes time, storage, credentials, and output handling.
- Native verification candidates from `tests/` and `examples/` should be selected narrowly and run only after task-specific setup is clear.
- IP-Adapter support is documented as deprecated in March 2026; surface this before recommending new long-lived IP-Adapter integrations.