FLUX Model Hugging Face

Minimal FLUX image-generation apps built around GGUF-quantized transformers from Hugging Face.

This repo contains two entry points:

• main.py: a Gradio UI for prompt-based image generation with saved previews.
• generate.py: a CLI workflow that prefetches model assets, loads a GGUF FLUX pipeline, and generates a single image.

What The Code Does

The project wraps FLUX diffusion pipelines from diffusers and downloads model weights from Hugging Face at runtime.

The Gradio app supports two model modes:

• R-rated: black-forest-labs/FLUX.1-dev with city96/FLUX.1-dev-gguf/flux1-dev-Q8_0.gguf
• Normal: black-forest-labs/FLUX.2-klein-9B with unsloth/FLUX.2-klein-9B-GGUF/flux-2-klein-9b-Q8_0.gguf
• The CLI script is focused on FLUX.1-dev and can optionally load the LoRA enhanceaiteam/Flux-uncensored-v2.
• Both scripts expect a CUDA-capable GPU and move the pipeline to cuda.
• Both scripts require a valid HF_TOKEN, and your Hugging Face account must have access to the gated model repos.

Repository Layout

• main.py: Gradio app with UI controls, image preview rendering, pipeline caching, and image saving to outputs/
• generate.py: terminal workflow for cache inspection, model prefetch, optional LoRA loading, and image generation to output.png
• requirements.txt: pip install list for running the project
• pyproject.toml: project metadata and dependencies
• .gitignore: excludes caches, virtualenvs, generated images, and logs

Requirements

• Python 3.12+
• NVIDIA GPU with CUDA support
• Enough VRAM for GGUF FLUX inference
• Hugging Face token with access to the referenced model repositories

The CLI script notes a setup around an RTX 4090 and logs the main GGUF file as roughly 12.7 GB.

Setup

python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Set your Hugging Face token before starting either app:

export HF_TOKEN=your_huggingface_token

You may also need to visit these repos in the browser and accept their license or gated access terms before running:

• https://huggingface.co/black-forest-labs/FLUX.1-dev
• https://huggingface.co/black-forest-labs/FLUX.2-klein-9B
• https://huggingface.co/enhanceaiteam/Flux-uncensored-v2

Run The Gradio UI

python main.py

What it does:

• Launches a Gradio app on 0.0.0.0
• Downloads the selected GGUF model on first use
• Caches pipelines in memory per model mode
• Saves generated images under outputs/
• Shows generated previews blurred by default until you unblur them in the UI

Run The CLI Script

Check cached assets only:

python generate.py --show-cache-only

Prefetch the required FLUX files and exit:

python generate.py --prefetch-only

Generate with the base model and skip LoRA loading:

python generate.py --skip-lora

Normal interactive generation:

python generate.py

The CLI script:

• Verifies or downloads required pipeline files one by one
• Loads the GGUF transformer in bfloat16
• Builds the FLUX pipeline from cached base files
• Optionally applies LoRA weights
• Prompts for text, steps, and guidance scale
• Saves the final image to output.png

Notes

• DIFFUSERS_GGUF_CUDA_KERNELS is disabled by default in both scripts to avoid incompatible prebuilt kernel issues.
• HF_HUB_DISABLE_XET=1 is set for download stability.
• HF_HUB_ENABLE_HF_TRANSFER=1 is enabled, but accelerated transfer only takes effect if hf_transfer is installed in your environment.
• Generated files and logs are intentionally ignored by Git.

Non-Essential Files Excluded

This published repo intentionally leaves out local-only artifacts such as:

• .git
• .venv
• .ruff_cache
• __pycache__
• generated images and logs