# ComfyUI-Boogu

Legacy ComfyUI custom nodes for [Boogu-Image-0.1](https://github.com/boogu-project/Boogu-Image).

## Recommended: Use Native ComfyUI Support

Boogu-Image is now supported natively in the main ComfyUI repository:

- ComfyUI: <https://github.com/Comfy-Org/ComfyUI>
- Native Boogu PR: <https://github.com/Comfy-Org/ComfyUI/pull/14523>
- ComfyUI model files: <https://huggingface.co/Comfy-Org/Boogu-Image>
- Original Boogu project: <https://github.com/boogu-project/Boogu-Image>

For most users, **do not install this custom node**. Update your existing ComfyUI
installation and use the native Boogu nodes and ComfyUI-repackaged model files.

### Native ComfyUI Setup

If you already have ComfyUI installed, update it first:

```bash
cd ComfyUI
git pull
pip install -r requirements.txt
```

Download the ComfyUI-repackaged Boogu model files from:

```text
https://huggingface.co/Comfy-Org/Boogu-Image
```

Place the files in the standard ComfyUI model folders:

```text
ComfyUI/models/
├── diffusion_models/
│   ├── boogu_image_base_bf16.safetensors
│   ├── boogu_image_base_fp8_scaled.safetensors
│   ├── boogu_image_base_nvfp4.safetensors
│   ├── boogu_image_edit_bf16.safetensors
│   ├── boogu_image_edit_nvfp4.safetensors
│   ├── boogu_image_turbo_bf16.safetensors
│   ├── boogu_image_turbo_fp8_scaled.safetensors
│   └── boogu_image_turbo_nvfp4.safetensors
├── loras/
│   └── boogu_image_turbo_lora_rank_128_bf16.safetensors
├── text_encoders/
│   └── qwen3vl_8b_fp8_scaled.safetensors
└── vae/
    └── flux1_vae_bf16.safetensors
```

Then start ComfyUI as usual:

```bash
python main.py
```

In native ComfyUI, Boogu uses standard ComfyUI model-loading nodes rather than
the legacy pipeline loader in this repository. Typical workflows use:

- `Load Diffusion Model` / `UNETLoader` for a `boogu_image_*` diffusion model
- `Load CLIP` with type `boogu` for `qwen3vl_8b_fp8_scaled.safetensors`
- `Load VAE` for `flux1_vae_bf16.safetensors`
- standard sampler and VAE decode nodes
- `TextEncodeBooguEdit` for image-edit workflows

If your models live outside the ComfyUI directory, use ComfyUI's standard
`extra_model_paths.yaml` mechanism to point `diffusion_models`, `text_encoders`,
`vae`, and `loras` to your external model folders.

## What This Repository Is

This repository is kept as a **legacy compatibility custom node**. It predates
the native ComfyUI integration and loads the original HuggingFace pipeline
folders directly:

```text
ComfyUI/models/boogu/
├── Boogu-Image-0.1-Base/
├── Boogu-Image-0.1-Edit/
└── Boogu-Image-0.1-Turbo/
```

Its legacy nodes are:

- `BOOGU: Load Base Pipeline`
- `BOOGU: Load Edit Pipeline`
- `BOOGU: Load Turbo Pipeline`
- `BOOGU: Generate`

Use this custom node only if you specifically need the old pipeline-folder
workflow. New users should use native ComfyUI support instead.

## Legacy Workflows

The `workflows/` directory contains old custom-node examples:

- `boogu_base_t2i.json`: `Load Base Pipeline -> Generate -> Preview`
- `boogu_edit_i2i.json`: `Load Edit Pipeline -> LoadImage -> Generate -> Preview`
- `boogu_turbo_t2i.json`: `Load Turbo Pipeline -> Generate -> Preview`

Prompt enhancement is intentionally not bundled in this repository. If you want
prompt enhancement, connect an external ComfyUI Qwen or LLM rewrite node to
`BOOGU: Generate` via the optional `instruction_override` input.

## Troubleshooting

`I already have ComfyUI installed. Do I need to install Boogu-Image first?`
: No. If you use the native ComfyUI integration, you do not need to install the
`Boogu-Image` Python package. Update ComfyUI and download the repackaged model
files from `Comfy-Org/Boogu-Image`.

`The legacy pipeline loader only searches ComfyUI/models/boogu`
: That limitation applies to this legacy custom node. Prefer native ComfyUI
support, which uses standard ComfyUI model folders and supports
`extra_model_paths.yaml`.

`ModuleNotFoundError: No module named 'boogu'`
: You are using this legacy custom node without installing the standalone
`Boogu-Image` package. Use native ComfyUI support instead, or install the
standalone package only if you need the legacy pipeline workflow.