Iris - a C inference pipeline for image synthesis models

Iris is an inference pipeline that generates images from text prompts using open weights diffusion transformer models. It is implemented entirely in C, with zero external dependencies beyond the C standard library. MPS, CUDA, ROCm and BLAS acceleration are optional but recommended. Under macOS, a BLAS API is part of the system, so nothing is required.

The name comes from the Greek goddess Iris, messenger of the gods and personification of the rainbow.

Supported model families:

• FLUX.2 Klein (by Black Forest Labs):
  • 4B distilled (4 steps, auto guidance set to 1, very fast).
  • 4B base (50 steps for max quality, or less. Classifier-Free Diffusion Guidance, much slower but more generation variety).
  • 9B distilled (4 steps, larger model, higher quality. Non-commercial license).
  • 9B base (50 steps, CFG, highest quality. Non-commercial license).
• Z-Image-Turbo (by Tongyi-MAI):
  • 6B (8 NFE / 9 scheduler steps, no CFG, fast).
• FLUX.3 Image Klein (by Black Forest Labs):
  • 5.6B distilled (16 steps by default, trained for 4 to 16, no CFG. FLUX Kommunity License).
  • 5.6B base (50 steps, CFG. FLUX Kommunity License). Implemented but not tested yet: the weights were not accessible at the time of writing.
  • Text-to-image, editing (-i image) and multi-reference generation (-i repeated).

All the models run fully on the GPU with the Metal (Apple), CUDA (NVIDIA) and ROCm (AMD) backends.

Quick Start

# Build (choose your backend)
make mps       # Apple Silicon (fastest)
# or: make cuda    # NVIDIA GPU
# or: make rocm    # AMD GPU
# or: make blas    # Intel Mac / Linux with OpenBLAS
# or: make generic # Pure C, no dependencies

# Download a model (~16GB) - pick one:
./download_model.sh 4b                   # using curl
# or: pip install huggingface_hub && python download_model.py 4b

# Generate an image
./iris -d flux-klein-4b -p "A woman wearing sunglasses" -o output.png

If you want to try the base model, instead of the distilled one (much slower, higher quality), use the following instructions. Use 10 steps if your computer is quite slow, instead of the default of 50, it will still work well enough to test it (10 seconds to generate a 256x256 image on a MacBook M3 Max).

./download_model.sh 4b-base
# or: pip install huggingface_hub && python download_model.py 4b-base
./iris -d flux-klein-4b-base -p "A woman wearing sunglasses" -o output.png

If you want to try the 9B model (higher quality, non-commercial license, ~30GB download):

# 9B is a gated model - you need a HuggingFace token
# 1. Accept the license at https://huggingface.co/black-forest-labs/FLUX.2-klein-9B
# 2. Get your token from https://huggingface.co/settings/tokens
./download_model.sh 9b --token YOUR_TOKEN
# or: python download_model.py 9b --token YOUR_TOKEN
# or: set HF_TOKEN env var
./iris -d flux-klein-9b -p "A woman wearing sunglasses" -o output.png

For Z-Image-Turbo:

# Download Z-Image-Turbo (~12GB)
pip install huggingface_hub && python download_model.py zimage-turbo
./iris -d zimage-turbo -p "a fish" -o fish.png

For FLUX.3 Image Klein (gated, accept the license on HuggingFace first, ~20GB):

./download_model.sh flux3 --token YOUR_TOKEN
# or: python download_model.py flux3 --token YOUR_TOKEN
./iris -d flux-3-klein -p "a fish" -o fish.png

That's it. No Python runtime required at inference time.

Example Output

Generated with: ./iris -d flux-klein-4b -p "A picture of a woman in 1960 America. Sunglasses. ASA 400 film. Black and White." -W 512 -H 512 -o woman.png

Image-to-Image Example

Generated with: ./iris -i antirez.png -o antirez_to_drawing.png -p "make it a drawing" -d flux-klein-4b

Features

• Zero dependencies: Pure C implementation, works standalone. BLAS optional for ~30x speedup (Apple Accelerate on macOS, OpenBLAS on Linux)
• GPU acceleration: Metal on Apple Silicon Macs (automatic), CUDA on NVIDIA and ROCm on AMD GPUs. On Apple Silicon it is faster than PyTorch's optimized MPS pipeline
• Runs where Python can't: Memory-mapped weights (default) enable inference on 8GB RAM systems where the Python ML stack cannot run at all
• Text-to-image: Generate images from text prompts
• Image-to-image: Transform existing images guided by prompts (Flux models)
• Multi-reference: Combine multiple reference images (e.g., -i car.png -i beach.png for "car on beach")
• Integrated text encoder: Qwen3 encoder built-in (4B or 8B depending on model, Qwen3-VL 4B for FLUX.3), no external embedding computation needed
• Memory efficient: Automatic encoder release after encoding (up to ~16GB freed)
• Memory-mapped weights: Enabled by default. Reduces peak memory from ~16GB to ~4-5GB. Fastest mode on MPS; BLAS users with plenty of RAM may prefer --no-mmap for faster inference
• Size-independent seeds: Same seed produces similar compositions at different resolutions. Explore at 256x256, then render at 512x512 with the same seed
• Terminal image display: watch the resulting image without leaving your terminal (Ghostty, Kitty, iTerm2, WezTerm, or Konsole).

Terminal Image Display

Display generated images directly in your terminal with --show, or watch the denoising process step-by-step with --show-steps:

# Display final image in terminal (auto-detects Kitty/Ghostty/iTerm2/WezTerm/Konsole)
./iris -d flux-klein-4b -p "a cute robot" -o robot.png --show

# Display each denoising step (slower, but interesting to watch)
./iris -d flux-klein-4b -p "a cute robot" -o robot.png --show-steps

This is the beginning of the README. Read the rest at the original. Read the full README ↗