Sign In
homemodelsimagesvideosarticlescomicschallengesupdatesshop

🍎 Creating AI Images on Apple macOS

18

Cyberdelia's Avatar

Cyberdelia

Forge Badge

Jun 9, 2026

(Updated: 15 days ago)

generation guide
appleforgeneoforgemacos
🍎 Creating AI Images on Apple macOS

Join The Tinkerer on Whop. Membership gets you early releases, private tools and a bunch of extra stuff.

👉 Join on Whop
💬 Join the community for support, free tools and early news on Discord

A focused guide for Apple Silicon (M1/M2/M3/M4) and Intel Mac users. For the full Forge Neo installation guide including Windows and Linux, see the main guide.

What to Expect

Forge Neo runs on macOS using Apple's Metal Performance Shaders (MPS) framework for GPU acceleration on Apple Silicon. It works, but there are important differences from a Windows/NVIDIA setup:

  • No CUDA — MPS is used instead on Apple Silicon, CPU-only on Intel Mac

  • No attention packages — --sage, --flash, --xformers, --nunchaku are NVIDIA-only and will not install

  • FP8 precision is not supported on MPS

  • GGUF K_M quants (Q4_K_M, Q5_K_M) produce broken output on Apple Silicon — use standard quants (Q4.1, Q5.0) instead

  • Generation is slower than a mid-range NVIDIA GPU — expect 5–15 minutes per image for Flux GGUF on an M-series chip

Requirements

  • macOS 13 (Ventura) or newer — MPS requires macOS 12.3+, but 13+ is recommended

  • Apple Silicon (M1/M2/M3/M4) for GPU acceleration, or Intel Mac for CPU-only

  • Git — brew install git

  • uv (recommended) — brew install uv

  • Python 3.13 (alternative to uv) — brew install [email protected]

  • FFmpeg (optional, video models only) — brew install ffmpeg

  • Homebrew — brew.sh

Installation

The ForgeNeo Toolkit handles all macOS-specific setup automatically: correct PyTorch build, MPS environment variables, unsupported flag filtering, and the restart loop.

Download (Free): ForgeNeo Toolkit on Whop

# Give the launcher execute permission (first time only)
chmod +x forge_neo_toolkit.sh
​
# Run
./forge_neo_toolkit.sh

Choose [3] Install Forge Neo and wait for the first launch to complete (10–30 minutes). For daily use: [1] Start Forge Neo.

Option B — Manual

# Install dependencies
brew install git uv ffmpeg
​
# Clone Forge Neo
git clone https://github.com/Haoming02/sd-webui-forge-classic sd-webui-forge-neo --branch neo
​
# Create virtual environment
cd sd-webui-forge-neo
uv venv venv --python 3.13 --seed
​
# Set execute permissions
chmod +x ./webui.sh ./webui-user.sh
​
# Configure webui-user.sh with macOS settings (see below)
# Then launch
./webui-user.sh

macOS Configuration

webui-user.sh

For manual installs, edit webui-user.sh with these macOS-specific settings:

#!/bin/bash
​
# Required: help uv find the venv
export VIRTUAL_ENV="/path/to/sd-webui-forge-neo/venv"
​
# Required: install standard PyTorch (no CUDA) instead of the +cuXXX build
export TORCH_COMMAND="pip install torch torchvision torchaudio"
​
# Required: allow Metal ops not yet implemented to fall back to CPU
export PYTORCH_ENABLE_MPS_FALLBACK="1"
​
# Recommended: --fast-fp16 enables fp16 accumulation for faster MPS inference
export COMMANDLINE_ARGS="--fast-fp16"
​
./webui.sh

Out-of-Memory fix (optional)

If you get OOM errors with large models (Flux, Wan 2.2), add this to webui-user.sh:

# Disables MPS memory limit — both watermarks set to 0 (no limit)
export PYTORCH_MPS_HIGH_WATERMARK_RATIO="0.0"
export PYTORCH_MPS_LOW_WATERMARK_RATIO="0.0"

⚠️ Setting only the HIGH watermark without adjusting LOW causes a crash: RuntimeError: invalid low watermark ratio. Always set both together.

⚠️ The Toolkit handles this automatically via MPS_WATERMARK_RATIO=0.0 in config.txt.

What You'll See on Startup

A healthy macOS startup looks like this:

Device: mps
VRAM State: SHARED
PyTorch Version: 2.12.0
Mac Version (26, 5, 1)
Using Basic Cross Attention
Using Slice Attention for VAE

  • Device: mps — GPU acceleration via Metal is active ✓

  • VRAM State: SHARED — unified memory, normal on Apple Silicon ✓

  • Using Basic Cross Attention — expected, no attention packages on macOS ✓

  • Memory Monitor Disabled — expected, CUDA monitor can't run on MPS ✓

These are not errors. They are the expected macOS output.

Launch Flags for macOS

FLAGEFFECTNOTES--fast-fp16fp16 accumulation for faster inferenceRecommended — added automatically by Toolkit--skip-torch-cuda-testSkip CUDA check at startupAdded automatically by smart launch

Flags that will NOT work on macOS and should not be added:

  • --sage — SageAttention, NVIDIA only

  • --flash — Flash Attention, NVIDIA only

  • --xformers — xformers, NVIDIA only

  • --nunchaku — Nunchaku kernels, NVIDIA only

  • --bnb — bitsandbytes, NVIDIA/Linux only

💡 The Toolkit automatically removes these flags if they appear in EXTRA_ARGS.

Model Recommendations for Apple Silicon

Use standard GGUF quants — avoid K_M

On Apple Silicon, GGUF models work well. However, K_M quant variants (Q4_K_M, Q5_K_M) produce broken output without any error message. Use standard quants instead:

  • ✅ Q4.1, Q5.0, Q6.0, Q8.0 — work correctly

  • ❌ Q4_K_M, Q5_K_M, Q6_K_M — broken on Apple Silicon

FP8 models

FP8 precision is not supported on macOS MPS. Use BF16 or GGUF variants instead.

Memory guidance for Apple Silicon unified memory

Apple Silicon uses unified memory, so your available RAM matters a lot when choosing models.

16 GB RAM

Recommended for lighter workflows:

  • SD 1.5

  • SDXL

  • Flux GGUF Q4

32 GB RAM

Recommended for heavier quantized models:

  • Flux GGUF Q5–Q8

  • Z-Image Turbo

  • Qwen-Image GGUF

64 GB RAM or more

Recommended for full-size and heavier models:

  • Full BF16 models

  • Wan 2.2

Troubleshooting

  • No matching distribution for torch==x.y.z+cu130 — CUDA torch on macOS. Fix: set TORCH_COMMAND="pip install torch torchvision torchaudio" before launching, or use the Toolkit which handles this automatically

  • RuntimeError: invalid low watermark ratio — set HIGH watermark without LOW. Fix: set both to 0.0 or leave both empty

  • Black or corrupted images — try adding --fp32-vae to COMMANDLINE_ARGS in webui-user.sh

  • ModuleNotFoundError: No module named 'psutil' — reinstall via Toolkit: [5] Repair → Venv Only

  • OOM crash with large models — add PYTORCH_MPS_HIGH_WATERMARK_RATIO=0.0 and PYTORCH_MPS_LOW_WATERMARK_RATIO=0.0

  • K_M GGUF produces green/noise output — switch to standard GGUF quants (Q4.1, Q5.0 etc.)

  • Permission denied on launch — run chmod +x forge_neo_toolkit.sh or chmod +x webui.sh

  • Failed to parse PyTorch version — harmless warning, Forge Neo is checking for CUDA version string it cannot find on macOS, does not affect generationx

18