Nunchaku Frequently Asked Questions

[lmxyy]

❗ Import Error: ImportError: cannot import name 'to_diffusers' from 'nunchaku.lora.flux' (...) (e.g., #250)

This error usually indicates that nunchaku was not installed properly. Please check the following common causes:

• You only installed the ComfyUI plugin (ComfyUI-nunchaku) but not the core nunchaku library. Please follow the installation instructions in our README to install the correct version of the nunchaku library.

• You installed nunchaku using pip install nunchaku, but this is the wrong package.
  The nunchaku name on PyPI is already taken by an unrelated project. Please uninstall the incorrect package and follow our installation guide to install the correct version.

• (MOST LIKELY) You installed nunchaku correctly, but into the wrong Python environment.
  If you're using the ComfyUI portable package, its Python interpreter is very likely not the system default. To identify the correct Python path, launch ComfyUI and check the several initial lines in the log. For example, you will find

  ** Python executable: G:\ComfyuI\python\python.exe
  

  To install nunchaku into this environment, use the following format:

  "G:\ComfyUI\python\python.exe" -m pip install <your-wheel-file>.whl

  Example (for Python 3.11 and torch 2.6):

  "G:\ComfyUI\python\python.exe" -m pip install https://github.com/mit-han-lab/nunchaku/releases/download/v0.2.0/nunchaku-0.2.0+torch2.6-cp311-cp311-linux_x86_64.whl

• You have a folder named nunchaku in your working directory.
  Python may mistakenly load from that local folder instead of the installed library. Also, make sure your plugin folder under custom_nodes is named ComfyUI-nunchaku, not nunchaku.

❗ Runtime Error: Assertion failed: this->shape.dataExtent == other.shape.dataExtent, file ...Tensor.h (e.g., #212)

This error is typically due to using the wrong model for your GPU.

• If you're using a Blackwell GPU (e.g., RTX 50-series), please use our FP4 models.
• For all other GPUs, use our INT4 models.

❓ PuLID Support (e.g., #258)

PuLID support is currently in development and will be included in the next major release.

❗ System crash or blue screen (e.g., #57)

We have observed some cases where memory is not properly released after image generation, especially when using ComfyUI. This may lead to system instability or crashes.

We’re actively investigating this issue. If you have experience or insights into memory management in ComfyUI, we would appreciate your help!

❗ Assertion Error: assert image_rotary_emb.shape[2] == batch_size * (txt_tokens + img_tokens) (e.g., #24)

Currently, batch sizes greater than 1 are not supported during inference. We will support this in a future major release.

❗ Assertion Error: Assertion failed: a.dtype() == b.dtype(), file ...misc_kernels.cu (e.g., #57)

At the moment, we only support the 16-bit version of ControlNet-Union-Pro. Support for FP8 and other ControlNets is planned for a future release.