Prove MPS before you install Forge on a Mac

The repository contains macOS and MPS code, but it does not publish a current Mac support matrix or a tested parity promise. Issue #2177 remains an unanswered request for clarification. We therefore label this route community-reported.

No. The published one-click archives contain Windows batch files and CUDA/PyTorch environments. On macOS, use a source clone only after the MPS preflight.

For the route on this page, yes: the current upstream PyTorch MPS instructions require Apple Silicon. A chip name alone still does not guarantee that a particular Forge model, dtype or extension will work.

No. Apple GPU acceleration in PyTorch uses the MPS backend. A non-fatal console warning mentioning CUDA can come from a CUDA-only monitor; the decisive checks are Device: mps and a successful MPS tensor probe.

The inspected Forge launcher is built around Python 3.10 and its macOS shell defaults pin PyTorch 2.3.1 on Apple Silicon. This page uses Homebrew [email protected] in a dedicated Forge virtual environment.

Homebrew may be installed but absent from the current shell PATH. On Apple Silicon, verify /opt/homebrew/bin/brew and follow the shellenv instructions printed by the official installer.

First confirm you launched ./webui.sh from the original Forge clone. Its macOS defaults include --skip-torch-cuda-test. If the process continues and Device: mps appears, a CUDA memory-monitor warning is not the same as a fatal startup exception.

Inside the Forge virtual environment, check torch.backends.mps.is_built(), torch.backends.mps.is_available(), and create a tensor on device="mps". All three checks must agree before you diagnose Forge.

That creates a new, unverified environment. A community report used a nightly build on an M2 Ultra, but the inspected Forge script pins 2.3.1. Preserve the working virtual environment and test a nightly only in a separate clone.

That is a dtype/backend mismatch, not a missing Forge flag. The open Forge report #2399 shows the failure while loading a GGUF FLUX setup. Return to the FP16 SD 1.5 baseline before testing newer model formats.

The model or text encoder is asking MPS to use an unsupported Float8 path. Do not patch the original checkout or hide the error. Record the exact model files and prove a plain FP16 baseline first.

Open original-repository reports show black output on multiple Apple Silicon machines and commits. Reset to a clean clone, correct model-family preset, one FP16 checkpoint, no LoRA, no extensions, 512×512 and batch size 1; then capture the first warning and infotext.

Close memory-heavy apps, use batch size 1, reduce dimensions, remove hires/upscale/ControlNet, and test a smaller model family. Unified memory is shared with macOS and other apps; installed RAM is not wholly available to Forge.

First prove the console says Device: mps. Then remove LoRAs and extensions and test a small baseline. PYTORCH_ENABLE_MPS_FALLBACK=1 can move unsupported operations to CPU, so a working generation can still be slow. Community timing cannot predict your Mac.

No. xformers and CUDA tuning flags target different backends. Start with the Forge macOS defaults and change one documented variable only after a reproducible baseline.

Community members have reported both success on a high-memory M2 Ultra and failures involving FP8, BF16 and GGUF. Original Forge does not publish a validated Mac FLUX recipe. This guide deliberately stops at an FP16 SD 1.5 baseline.

The inspected launcher supports --forge-ref-a1111-home, and dated community reports use it. First make both installations work independently and never share their virtual environments.

Stop Forge and move only the dedicated forge-mac-lab folder to Trash. If you created a separate virtual environment inside that folder, it goes with the clone. Do not delete Homebrew, Python, Git or another UI installation as part of this rollback.