Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio sd.cpp: --mmap for CPU renders on builds whose --mmap keeps the CPU repack (#16758)

Daniel Hanc014c8b3664a
diff --git a/studio/backend/core/inference/sd_cpp_args.py b/studio/backend/core/inference/sd_cpp_args.py
index c5f96efdeec..0bf59a0efc9 100644
--- a/studio/backend/core/inference/sd_cpp_args.py
+++ b/studio/backend/core/inference/sd_cpp_args.py
@@ -410,8 +410,10 @@ def metal_placement_flags(offload: Sequence[str]) -> list[str]:
return [f for f in flags if f not in offload]
-# 1 / 0 forces sd.cpp's --mmap on / off on macOS; unset decides from the installed build (``mac_mmap_flags``).
+# 1 / 0 forces sd.cpp's --mmap on / off; unset decides from the installed build (``mmap_flags``).
SD_CPP_MMAP_ENV = "UNSLOTH_DIFFUSION_SD_CPP_MMAP"
+# Help text of builds whose --mmap still repacks CPU weights (older ones run them unrepacked: slower, other pixels).
+CPU_MMAP_REPACK_HELP = "weights the CPU repacks are still loaded"
# leejet/stable-diffusion.cpp#2037 (master-907) maps mmapped weights through Metal device buffers. Older builds accept
# --mmap but hand Metal a CPU buffer it cannot address, so the flag is only safe from this build on.
METAL_MMAP_MIN_BUILD = 907
@@ -499,6 +501,73 @@ def mac_mmap_flags(binary: Optional[str], extra_args: Optional[Sequence[str]] =
return ["--mmap"] if build is not None and build >= METAL_MMAP_MIN_BUILD else []
[email protected]_cache(maxsize = 8)
+def _installed_sd_cpp_accelerator(binary: str) -> Optional[str]:
+ """The accelerator class (``cpu`` / ``cuda`` / ``vulkan`` / ...) Studio's installer recorded next to ``binary``."""
+ import json
+ from pathlib import Path
+
+ try:
+ path = Path(binary).resolve()
+ except Exception: # noqa: BLE001
+ return None
+ for parent in list(path.parents)[:3]:
+ try:
+ with open(parent / _INSTALL_RECORD, "r", encoding = "utf-8") as f:
+ rec = json.load(f)
+ except (OSError, ValueError):
+ continue
+ accel = rec.get("accelerator") if isinstance(rec, dict) else None
+ return accel if isinstance(accel, str) and accel else None
+ return None
+
+
+def sd_cpp_mmap_keeps_cpu_repack(binary: str) -> bool:
+ """True when ``binary --help`` says its --mmap still repacks CPU weights. Fails closed."""
+ try:
+ st = os.stat(binary)
+ except OSError:
+ return False
+ return _cpu_mmap_repack_in_help(str(binary), st.st_size, st.st_mtime_ns)
+
+
[email protected]_cache(maxsize = 16)
+def _cpu_mmap_repack_in_help(binary: str, size: int, mtime_ns: int) -> bool:
+ from core.inference.sd_cpp_backend import _sd_cpp_probe_output
+ text = _sd_cpp_probe_output(binary, "--help")
+ return text is not None and CPU_MMAP_REPACK_HELP in text
+
+
+def mmap_flags(
+ binary: Optional[str],
+ extra_args: Optional[Sequence[str]] = None,
+ backend_args: Optional[Sequence[str]] = None,
+) -> list[str]:
+ """``--mmap`` on macOS Metal-mmap builds and on CPU renders whose --mmap still repacks CPU weights (keeps
+ unrepacked weights file-backed: ~4.6 GB vs 13.3 GB anonymous, pixel-identical). GPU renders are left alone."""
+ import sys
+
+ if sys.platform == "darwin":
+ return mac_mmap_flags(binary, extra_args)
+ if "--mmap" in (extra_args or ()):
+ return []
+ forced = os.environ.get(SD_CPP_MMAP_ENV, "").strip().lower()
+ if forced in ("0", "false", "no", "off"):
+ return []
+ if forced in ("1", "true", "yes", "on"):
+ return ["--mmap"]
+ if not binary:
+ return []
+ args = [*(backend_args or ()), *(extra_args or ())]
+ target = _diffusion_backend([args[i + 1] for i, f in enumerate(args[:-1]) if f == "--backend"])
+ on_cpu = (
+ target.lower() == "cpu"
+ if target is not None
+ else _installed_sd_cpp_accelerator(str(binary)) == "cpu"
+ )
+ return ["--mmap"] if on_cpu and sd_cpp_mmap_keeps_cpu_repack(str(binary)) else []
+
+
# Everything on the CPU backend. sd.cpp prefers GPU -> integrated GPU -> CPU and only `--backend` changes which
# backend EXECUTES the graph (`--offload-to-cpu` moves parameters, not compute), so this is the one flag that removes
# ggml-metal entirely.
@@ -819,7 +888,7 @@ def build_sd_cpp_command(
if offload:
cmd += offload
cmd += metal_placement_flags(offload)
- cmd += mac_mmap_flags(binary, extra_args)
+ cmd += mmap_flags(binary, extra_args, offload)
if verbose:
cmd += ["-v"]
if extra_args:
@@ -917,7 +986,7 @@ def build_sd_cpp_video_command(
if offload:
cmd += offload
cmd += metal_placement_flags(offload)
- cmd += mac_mmap_flags(binary, extra_args)
+ cmd += mmap_flags(binary, extra_args, offload)
if verbose:
cmd.append("-v")
if extra_args:
@@ -1025,7 +1094,7 @@ def build_sd_cpp_server_command(
native_speed_flags(native_speed, backend_args, accelerator, binary), offload
)
cmd += placement
- cmd += mac_mmap_flags(binary, extra_args)
+ cmd += mmap_flags(binary, extra_args, offload)
if verbose:
cmd += ["-v"]
if extra_args:
diff --git a/studio/backend/tests/test_sd_cpp_args.py b/studio/backend/tests/test_sd_cpp_args.py
index 0266d00f1db..7431f6dcfd4 100644
--- a/studio/backend/tests/test_sd_cpp_args.py
+++ b/studio/backend/tests/test_sd_cpp_args.py
@@ -1104,6 +1104,84 @@ def test_mmap_env_override_and_no_duplicate(monkeypatch, tmp_path):
assert cmd.count("--mmap") == 1
+# ── CPU mmap (repack-aware builds) ──────────────────────────────────────────
+
+_REPACK_HELP = " --mmap whether to memory-map model (CPU: weights the CPU repacks are still loaded and repacked)\n"
+_OLD_HELP = " --mmap whether to memory-map model\n"
+
+
+def _cpu_install(
+ tmp_path,
+ monkeypatch,
+ help_text,
+ accelerator = "cpu",
+):
+ import json
+
+ import core.inference.sd_cpp_backend as backend
+
+ root = tmp_path / f"sd-{accelerator}-{abs(hash(help_text)) % 10**6}"
+ (root / "bin").mkdir(parents = True)
+ binary = root / "bin" / "sd-cli"
+ binary.write_text("")
+ (root / ".unsloth-sd-cpp-install.json").write_text(
+ json.dumps({"tag": "master-982-0518b34-uaba3a1c", "accelerator": accelerator})
+ )
+ for fn in (
+ _sd_cpp_args_module._installed_sd_cpp_tag,
+ _sd_cpp_args_module._installed_sd_cpp_accelerator,
+ _sd_cpp_args_module._cpu_mmap_repack_in_help,
+ ):
+ fn.cache_clear()
+ monkeypatch.setattr(backend, "_sd_cpp_probe_output", lambda b, *a, **k: help_text)
+ return str(binary)
+
+
[email protected]("platform", ["linux", "win32"])
+def test_cpu_mmap_on_repack_aware_cpu_builds_only(monkeypatch, tmp_path, platform):
+ monkeypatch.delenv("UNSLOTH_DIFFUSION_SD_CPP_MMAP", raising = False)
+ monkeypatch.setattr("sys.platform", platform)
+ new = _cpu_install(tmp_path, monkeypatch, _REPACK_HELP)
+ for cmd in _all_builders(new):
+ assert cmd.count("--mmap") == 1
+ # The pinned build maps repackable weights and runs them unrepacked: never sent there.
+ old = _cpu_install(tmp_path, monkeypatch, _OLD_HELP)
+ assert all("--mmap" not in cmd for cmd in _all_builders(old))
+ for accel in ("cuda", "vulkan", "rocm"):
+ gpu = _cpu_install(tmp_path, monkeypatch, _REPACK_HELP, accelerator = accel)
+ assert all("--mmap" not in cmd for cmd in _all_builders(gpu))
+
+
+def test_cpu_mmap_follows_an_explicit_backend(monkeypatch, tmp_path):
+ from core.inference.sd_cpp_args import mmap_flags
+
+ monkeypatch.delenv("UNSLOTH_DIFFUSION_SD_CPP_MMAP", raising = False)
+ monkeypatch.setattr("sys.platform", "linux")
+ gpu = _cpu_install(tmp_path, monkeypatch, _REPACK_HELP, accelerator = "vulkan")
+ assert mmap_flags(gpu, None, ["--backend", "cpu"]) == ["--mmap"]
+ cpu = _cpu_install(tmp_path, monkeypatch, _REPACK_HELP)
+ assert mmap_flags(cpu, None, ["--backend", "diffusion=vulkan0"]) == []
+ assert mmap_flags(cpu, ["--mmap"], None) == []
+ assert mmap_flags(None, None, None) == []
+ # an unreadable / unprobeable binary fails closed
+ assert (
+ _cpu_install(tmp_path, monkeypatch, None)
+ and mmap_flags(str(tmp_path / "missing" / "sd-cli")) == []
+ )
+
+
+def test_cpu_mmap_env_override(monkeypatch, tmp_path):
+ from core.inference.sd_cpp_args import mmap_flags
+
+ monkeypatch.setattr("sys.platform", "linux")
+ new = _cpu_install(tmp_path, monkeypatch, _REPACK_HELP)
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_SD_CPP_MMAP", "0")
+ assert mmap_flags(new) == []
+ monkeypatch.setenv("UNSLOTH_DIFFUSION_SD_CPP_MMAP", "1")
+ old = _cpu_install(tmp_path, monkeypatch, _OLD_HELP)
+ assert mmap_flags(old) == ["--mmap"]
+
+
@pytest.mark.parametrize(
"ccs,expected",
[