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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""The scripts only report UNSLOTH_LLAMA_CPP_BACKEND; install_llama_prebuilt.py reads it."""
import os
import re
import shutil
import subprocess
import sys
from pathlib import Path
import pytest
# All pwsh spawns go through run_pwsh: parallel startups race on the shared cache and SIGABRT.
from unsloth_pwsh_runner import run_pwsh
_STUDIO = Path(__file__).resolve().parents[2]
_SETUP_SH = _STUDIO / "setup.sh"
_SETUP_PS1 = _STUDIO / "setup.ps1"
_SKIP_NO_BASH = pytest.mark.skipif(shutil.which("bash") is None, reason = "bash unavailable")
_SKIP_NO_PWSH = pytest.mark.skipif(shutil.which("pwsh") is None, reason = "pwsh unavailable")
def _backend_block() -> str:
text = _SETUP_SH.read_text(encoding = "utf-8")
m = re.search(r"# Reporting only:.*?esac", text, re.DOTALL)
assert m, "UNSLOTH_LLAMA_CPP_BACKEND block not found in setup.sh"
return m.group(0)
def _run(value: str | None, system: str = "Linux") -> tuple[list[str], str]:
# Pass the value via env so whitespace survives; stub the setup.sh log helpers.
env = {
k: v
for k, v in os.environ.items()
if k not in ("UNSLOTH_LLAMA_CPP_BACKEND", "UNSLOTH_FORCE_VULKAN")
}
if value is not None:
env["UNSLOTH_LLAMA_CPP_BACKEND"] = value
harness = (
f'set -u\n_PREBUILT_CMD=()\nC_WARN=""\nC_OK=""\n_HOST_SYSTEM="{system}"\n'
'_source_backend_choice="$(printf \'%s\' "${UNSLOTH_LLAMA_CPP_BACKEND:-}" '
"| awk '{$1=$1; print tolower($0)}')\"\n"
'_source_legacy_force_vulkan="$(printf \'%s\' "${UNSLOTH_FORCE_VULKAN:-}" '
"| awk '{$1=$1; print tolower($0)}')\"\n"
'_explicit_llama_source_backend=""\n'
'step() { printf "STEP: %s\\n" "$*" >&2; }\n'
f"{_backend_block()}\n"
'printf "%s\\n" "${_PREBUILT_CMD[@]}"'
)
out = subprocess.run(
["bash", "-c", harness], capture_output = True, text = True, env = env, check = True
)
return out.stdout.split(), out.stderr
def test_backend_block_forwards_nothing_to_the_installer():
# install_llama_prebuilt.py owns the selection; it alone can read the marker's recorded choice.
assert "_PREBUILT_CMD" not in _backend_block()
@_SKIP_NO_BASH
@pytest.mark.parametrize("value", ["cpu", "CPU", "Cpu", " cpu ", "CPU\t"])
def test_backend_cpu_is_accepted(value):
args, stderr = _run(value)
assert args == []
assert "Ignoring" not in stderr
@_SKIP_NO_BASH
@pytest.mark.parametrize("value", ["cpu", "CPU", " cpu "])
def test_backend_cpu_macos_warns(value):
args, stderr = _run(value, system = "Darwin")
assert args == []
assert "macOS" in stderr
@_SKIP_NO_BASH
@pytest.mark.parametrize("value", [None, "", "auto", "AUTO", " "])
def test_backend_auto_is_silent(value):
args, stderr = _run(value)
assert args == []
assert stderr == ""
@_SKIP_NO_BASH
@pytest.mark.parametrize("value", ["vulkan", "VULKAN", " vulkan "])
def test_backend_vulkan_is_reported(value):
args, stderr = _run(value)
assert args == []
assert "Vulkan selected for GGUF inference" in stderr
assert "Ignoring" not in stderr
@_SKIP_NO_BASH
@pytest.mark.parametrize("value", ["vulkan", "VULKAN"])
def test_backend_vulkan_macos_warns(value):
args, stderr = _run(value, system = "Darwin")
assert args == []
assert "Metal" in stderr
@_SKIP_NO_BASH
@pytest.mark.parametrize("value", ["hip", "HIP", "rocm", " ROCM ", "cuda", " CUDA "])
def test_backend_gpu_opt_out_is_accepted(value):
args, stderr = _run(value)
assert args == []
assert "Ignoring" not in stderr
@_SKIP_NO_BASH
@pytest.mark.parametrize("value", ["gpu", "sycl"])
def test_backend_unknown_warns(value):
args, stderr = _run(value)
assert args == []
assert "Ignoring" in stderr
@_SKIP_NO_BASH
def test_arm64_recovery_uses_transient_cpu_fallback():
# The arm64 Linux GPU-build recovery must stay transient (--cpu-fallback), never
# the persisted --force-cpu, so a later update can still heal to a GPU bundle (#6097).
text = _SETUP_SH.read_text(encoding = "utf-8")
m = re.search(r"_ARM64_CPU_CMD=\((.*?)\)", text, re.DOTALL)
assert m, "arm64 CPU recovery command not found in setup.sh"
block = m.group(1)
assert "--cpu-fallback" in block
assert "--force-cpu" not in block
def test_ordinary_prebuilt_failure_does_not_re_derive_the_backend():
# An unhonoured request (env or marker) exits 5 and fails closed; exit 2 means no concrete backend.
sh = _SETUP_SH.read_text(encoding = "utf-8")
failure = sh.index('step "llama.cpp" "prebuilt install failed"')
branch = sh[failure : sh.index("_NEED_LLAMA_SOURCE_BUILD=true", failure)]
assert "_explicit_llama" not in branch
ps1 = _SETUP_PS1.read_text(encoding = "utf-8")
failure = ps1.index('step "llama.cpp" "prebuilt install failed"')
branch = ps1[failure : ps1.index("$NeedLlamaSourceBuild = $true", failure)]
assert "explicitLlama" not in branch
def test_unavailable_named_backend_never_falls_through_to_source():
sh = _SETUP_SH.read_text(encoding = "utf-8")
unavailable = sh.index('elif [ "$_PREBUILT_STATUS" -eq 5 ]; then')
ordinary_fallback = sh.index('elif [ "$_PREBUILT_STATUS" -eq 2 ]; then', unavailable)
guarded = sh[unavailable:ordinary_fallback]
assert "will not substitute a different source backend" in guarded
assert "_NEED_LLAMA_SOURCE_BUILD=true" not in guarded
assert "setup_fail 1" in guarded
ps1 = _SETUP_PS1.read_text(encoding = "utf-8")
unavailable = ps1.index("} elseif ($prebuiltExit -eq 5) {")
ordinary_fallback = ps1.index("} elseif ($prebuiltExit -eq 2) {", unavailable)
guarded = ps1[unavailable:ordinary_fallback]
assert "will not substitute a different source backend" in guarded
assert "$NeedLlamaSourceBuild = $true" not in guarded
assert "Exit-SetupFailure" in guarded
def test_explicit_backend_source_build_fails_closed():
sh = _SETUP_SH.read_text(encoding = "utf-8")
local_branch = sh.index('if [ "$_LOCAL_LLAMA_CPP_LINKED" = true ]; then')
prebuilt_branch = sh.index('elif [ "$_LLAMA_FORCE_COMPILE" = "1" ]; then', local_branch)
guarded = sh[local_branch:prebuilt_branch]
assert (
'elif [ -n "$_explicit_llama_source_backend" ] && '
'[ "$_NEED_LLAMA_SOURCE_BUILD" = true ]; then'
) in guarded
assert "Explicit backend selection requires a matching prebuilt bundle" in guarded
assert "setup_fail 1" in guarded
ps1 = _SETUP_PS1.read_text(encoding = "utf-8")
local_branch = ps1.index("if ($LocalLlamaCppLinked) {")
prebuilt_branch = ps1.index(
'} elseif ($env:UNSLOTH_LLAMA_FORCE_COMPILE -eq "1") {', local_branch
)
guarded = ps1[local_branch:prebuilt_branch]
assert "} elseif ($explicitLlamaSourceBackend -and $NeedLlamaSourceBuild) {" in guarded
assert "Explicit backend selection requires a matching prebuilt bundle" in guarded
assert "Exit-SetupFailure" in guarded
def test_force_compile_sets_need_source_build_before_backend_guard():
# The source-build state must be set before the explicit-backend guard runs.
sh = _SETUP_SH.read_text(encoding = "utf-8")
force_compile_set = sh.index(
'if [ "$_LLAMA_FORCE_COMPILE" = "1" ]; then\n _NEED_LLAMA_SOURCE_BUILD=true'
)
backend_guard = sh.index('elif [ -n "$_explicit_llama_source_backend" ] && ')
assert force_compile_set < backend_guard
ps1 = _SETUP_PS1.read_text(encoding = "utf-8")
force_compile_set = ps1.index(
'if ($env:UNSLOTH_LLAMA_FORCE_COMPILE -eq "1") {\n $NeedLlamaSourceBuild = $true'
)
backend_guard = ps1.index("} elseif ($explicitLlamaSourceBackend -and $NeedLlamaSourceBuild) {")
assert force_compile_set < backend_guard
def test_legacy_force_vulkan_gets_the_same_strict_fallback():
sh = _SETUP_SH.read_text(encoding = "utf-8")
assert '1|true|yes|on) _explicit_llama_source_backend="vulkan"' in sh
ps1 = _SETUP_PS1.read_text(encoding = "utf-8")
assert '$sourceLegacyForceVulkan -in @("1", "true", "yes", "on")' in ps1
assert '$explicitLlamaSourceBackend = "vulkan"' in ps1
def _source_backend_choice_block() -> str:
text = _SETUP_SH.read_text(encoding = "utf-8")
m = re.search(
r'_source_backend_choice="\$\(printf.*?\n.*?_explicit_llama_source_backend=""\n'
r".*?\nfi\n",
text,
re.DOTALL,
)
assert m, "_source_backend_choice block not found in setup.sh"
return m.group(0)
@_SKIP_NO_BASH
@pytest.mark.parametrize(
"backend, force_vulkan, expected_backend, expected_explicit",
[
(None, None, "", ""),
(None, "on", "", "vulkan"),
("vulkan", None, "vulkan", "vulkan"),
("auto", "on", "auto", ""),
("banana", "1", "banana", "vulkan"),
("cpu", "1", "cpu", "cpu"),
("cuda", "1", "cuda", "cuda"),
("hip", "1", "hip", "rocm"),
("rocm", "1", "rocm", "rocm"),
],
)
def test_llama_backend_source_choice_in_setup_sh(
backend, force_vulkan, expected_backend, expected_explicit
):
env = {
k: v
for k, v in os.environ.items()
if k not in ("UNSLOTH_LLAMA_CPP_BACKEND", "UNSLOTH_FORCE_VULKAN")
}
if backend is not None:
env["UNSLOTH_LLAMA_CPP_BACKEND"] = backend
if force_vulkan is not None:
env["UNSLOTH_FORCE_VULKAN"] = force_vulkan
harness = (
"set -u\n_HOST_SYSTEM=Linux\n"
f"{_source_backend_choice_block()}\n"
'printf "%s:%s" "$_source_backend_choice" "$_explicit_llama_source_backend"'
)
out = subprocess.run(
["bash", "-c", harness], capture_output = True, text = True, env = env, check = True
)
assert out.stdout == f"{expected_backend}:{expected_explicit}"
def _ps1_search(pattern: str, flags = 0) -> str:
m = re.search(pattern, _SETUP_PS1.read_text(encoding = "utf-8"), flags)
assert m, f"setup.ps1 block not found: {pattern}"
return m.group(0)
@_SKIP_NO_PWSH
@pytest.mark.parametrize(
"backend, force_vulkan, expected_explicit",
[
(None, None, ""),
(None, "on", "vulkan"),
("vulkan", None, "vulkan"),
("auto", "on", ""),
("cpu", "1", "cpu"),
("cuda", "1", "cuda"),
("hip", "1", "rocm"),
("rocm", "1", "rocm"),
],
)
def test_llama_backend_source_choice_in_setup_ps1(backend, force_vulkan, expected_explicit):
normalize = _ps1_search(
r'\$sourceLlamaBackend = "\$\(\$env:UNSLOTH_LLAMA_CPP_BACKEND\)".*?'
r"\$explicitLlamaSourceBackend = \$null.*?\n\}",
re.DOTALL,
)
env = {
k: v
for k, v in os.environ.items()
if k not in ("UNSLOTH_LLAMA_CPP_BACKEND", "UNSLOTH_FORCE_VULKAN")
}
if backend is not None:
env["UNSLOTH_LLAMA_CPP_BACKEND"] = backend
if force_vulkan is not None:
env["UNSLOTH_FORCE_VULKAN"] = force_vulkan
out = run_pwsh(
[
"pwsh",
"-NoProfile",
"-Command",
# Brace the name: PowerShell reads "$var:" as a scope qualifier.
f'{normalize}\n"RESULT:${{sourceLlamaBackend}}:$explicitLlamaSourceBackend"',
],
capture_output = True,
text = True,
env = env,
check = True,
)
expected_backend = (backend or "").strip().lower()
assert out.stdout.strip() == f"RESULT:{expected_backend}:{expected_explicit}"
def _run_ps1(value: str | None, extra_env: dict[str, str] | None = None) -> str:
normalize = _ps1_search(
r"\$llamaBackend = \$sourceLlamaBackend.*?Ignoring UNSLOTH_LLAMA_CPP_BACKEND.*?\n\s*\}",
re.DOTALL,
)
assert "$prebuiltArgs" not in normalize, normalize
env = {
k: v
for k, v in os.environ.items()
if k not in ("UNSLOTH_LLAMA_CPP_BACKEND", "UNSLOTH_FORCE_VULKAN")
}
if value is not None:
env["UNSLOTH_LLAMA_CPP_BACKEND"] = value
env.update(extra_env or {})
harness = (
# Stub setup.ps1's Write-StudioLine sink so the warning lands on stdout.
"function Write-StudioLine { param([string]$Message, [string]$ForegroundColor) "
"Write-Host $Message }\n"
"$prebuiltArgs = @()\n"
'$sourceLlamaBackend = "$($env:UNSLOTH_LLAMA_CPP_BACKEND)".Trim().ToLowerInvariant()\n'
'$sourceLegacyForceVulkan = "$($env:UNSLOTH_FORCE_VULKAN)".Trim().ToLowerInvariant()\n'
"$explicitLlamaSourceBackend = $null\n"
f'{normalize}\n"ARGS:" + ($prebuiltArgs -join ",")'
)
out = run_pwsh(
["pwsh", "-NoProfile", "-Command", harness],
capture_output = True,
text = True,
env = env,
check = True,
)
return out.stdout
@_SKIP_NO_PWSH
@pytest.mark.parametrize(
"value", ["cpu", "CPU", "Cpu", " cpu ", "CPU\t", None, "", "auto", "AUTO", " "]
)
def test_ps1_backend_forwards_no_arguments(value):
out = _run_ps1(value)
assert out.strip() == "ARGS:"
@_SKIP_NO_PWSH
@pytest.mark.parametrize("value", ["vulkan", "VULKAN", " vulkan "])
def test_ps1_backend_vulkan_is_reported(value):
out = _run_ps1(value)
assert "Vulkan selected for GGUF inference" in out
assert "Ignoring" not in out
@_SKIP_NO_PWSH
@pytest.mark.parametrize("value", ["cuda", " CUDA ", "hip", "HIP", "rocm", " ROCM "])
def test_ps1_backend_gpu_opt_out_is_accepted(value):
out = _run_ps1(value)
assert out.strip() == "ARGS:"
@_SKIP_NO_PWSH
@pytest.mark.skipif(sys.platform == "darwin", reason = "the branch reads $IsMacOS, read-only in pwsh")
def test_ps1_forced_vulkan_reaches_the_installer_on_windows_arm64():
# The installer resolves the Windows ARM64 Vulkan bundle (#11674), so setup must not refuse first.
out = _run_ps1(
"vulkan",
{"OS": "Windows_NT", "PROCESSOR_ARCHITECTURE": "ARM64", "PROCESSOR_ARCHITEW6432": ""},
)
assert "Vulkan selected for GGUF inference" in out
@_SKIP_NO_PWSH
@pytest.mark.parametrize("value", ["gpu", "sycl"])
def test_ps1_backend_unknown_warns(value):
out = _run_ps1(value)
assert "Ignoring" in out