SKILL.md — mflux

Name

mflux

Description

Generate images locally using Apple Silicon via the mflux MLX implementation. Supports FLUX.2-klein-4B (default, fastest 4-step generation, Apache 2.0 licensed) and Z-Image-Turbo (6B, highest quality). All processing is on-device — no cloud, no API keys, no data leaving your Mac.

Requirements

• Apple Silicon Mac (M1 or later)
• Python 3.10+
• macOS 13.5+
• Recommended: 16GB+ RAM (8GB works with quantization)

Installation

1. Install mflux (via uv - recommended)

uv tool install --upgrade mflux --prerelease=allow

With faster downloads (optional):

uv tool install --upgrade mflux --with hf_transfer --prerelease=allow

2. Alternative: Install via pip

pip install -U mflux

3. Verify installation

mflux-generate --help
mflux-generate-z-image-turbo --help
mflux-generate-flux2 --help

Python API Usage

Quick Start — FLUX.2 Klein 4B (Default, Fastest)

from mflux.models.flux2.variants import Flux2Klein
from mflux.models.common.config import ModelConfig

model = Flux2Klein(model_config=ModelConfig.flux2_klein_4b())
image = model.generate_image(
    prompt="A serene Japanese garden with cherry blossoms, golden afternoon light",
    num_inference_steps=4,  # Only 4 steps needed!
    width=1024,
    height=768,
    seed=42,
)
image.save("garden.png")

Z-Image Turbo (Highest Quality)

from mflux.models.z_image import ZImage
from mflux.models.common.config import ModelConfig

model = ZImage(
    model_config=ModelConfig.z_image_turbo(),
    model_path="filipstrand/Z-Image-Turbo-mflux-4bit",  # 4-bit quantized
)
image = model.generate_image(
    prompt="A majestic eagle soaring over snow-capped mountains at sunset",
    num_inference_steps=9,
    width=1280,
    height=720,
    seed=42,
)
image.save("eagle.png")

With Quantization (Lower RAM)

from mflux.models.flux2.variants import Flux2Klein
from mflux.models.common.config import ModelConfig

model = Flux2Klein(
    model_config=ModelConfig.flux2_klein_4b(),
    quantize=8,  # 8-bit quantization
)
# ... generate image

Image-to-Image

from PIL import Image
from mflux.models.flux2.variants import Flux2Klein

model = Flux2Klein(model_config=ModelConfig.flux2_klein_4b())
image = model.generate_image(
    prompt="Transform into a watercolor painting",
    num_inference_steps=4,
    init_image=Image.open("source.jpg"),
    init_image_strength=0.3,  # 0.0-1.0, higher = more change
)
image.save("watercolor.png")

FLUX.2 Image Editing

from mflux.models.flux2.variants import Flux2KleinEdit
from mflux.models.common.config import ModelConfig

model = Flux2KleinEdit(model_config=ModelConfig.flux2_klein_4b())
image = model.generate_image(
    prompt="Make the person wear sunglasses",
    image_paths=["person.jpg", "sunglasses.jpg"],
    num_inference_steps=4,
    seed=42,
)
image.save("edited.png")

LoRA Support

from mflux.models.flux2.variants import Flux2Klein
from mflux.models.common.config import ModelConfig

model = Flux2Klein(
    model_config=ModelConfig.flux2_klein_4b(),
    lora_paths=["path/to/lora.safetensors"],
    lora_scales=[0.8],
)
# ... generate image

Supported Models

CLI Reference

Generate with FLUX.2 Klein

# Default 4B model, 4 steps
mflux-generate-flux2 \
  --prompt "A photorealistic portrait of a wise old sailor" \
  --width 1024 \
  --height 768 \
  --steps 4 \
  --seed 42

# 9B model for higher quality
mflux-generate-flux2 \
  --model flux2-klein-9b \
  --prompt "A cyberpunk cityscape with neon lights" \
  --steps 4

# Base model (non-distilled, more steps)
mflux-generate-flux2 \
  --model flux2-klein-base-4b \
  --prompt "A detailed oil painting of a forest" \
  --steps 50 \
  --guidance 1.5

Generate with Z-Image Turbo

mflux-generate-z-image-turbo \
  --prompt "A minimalist logo design for a coffee shop" \
  --width 1280 \
  --height 720 \
  --steps 9 \
  --seed 42

# With LoRA
mflux-generate-z-image-turbo \
  --prompt "Art nouveau style portrait of a woman" \
  --steps 9 \
  --lora-paths "renderartist/Art-Nouveau-Style" \
  --lora-scales 0.7

With Quantization

mflux-generate-flux2 \
  --prompt "A serene landscape" \
  --quantize 8  # 8-bit quantization (reduces RAM)

# Or 4-bit for lowest RAM
mflux-generate-flux2 \
  --prompt "A serene landscape" \
  --quantize 4

Parameters

Aspect Ratios (Recommended Sizes)

Performance & RAM Guide

Model Weights

Models are downloaded automatically on first use:

• FLUX.2-klein-4b: ~15GB
• FLUX.2-klein-9b: ~32GB
• Z-Image-Turbo quantized: ~8GB

Cache location: ~/.cache/huggingface/

Comparison: When to Use Which

Choose FLUX.2-klein-4b when:

• Speed is priority (4 steps, ~5-8 sec)
• Apache 2.0 license needed (commercial use)
• Generating many images fast
• 8GB+ RAM available

Choose Z-Image-Turbo when:

• Quality is priority
• Realism matters most
• You have 16GB+ RAM
• Time per image acceptable

Choose FLUX.2-klein-9b when:

• Best quality from Apache-licensed model
• 16GB+ RAM available
• Commercial use required

Error Handling