unsloth/studio/backend/utils
Naitik Pal cf912cbd88
feat(studio): add UNSLOTH_LLAMA_CPP_BACKEND env var to force CPU fallback #7213 (#7228)
* test(studio): add e2e test for cpu-fallback overriding vulkan

* feat(studio): add UNSLOTH_LLAMA_CPP_BACKEND env var

* feat(studio): add UNSLOTH_LLAMA_CPP_BACKEND env var

* Preserve UNSLOTH_LLAMA_CPP_BACKEND=cpu across llama.cpp updates for PR #7228

The in-app updater rebuilt the installer command without --cpu-fallback and
only re-asserted Vulkan, so accepting a llama.cpp update after forcing CPU on
an Intel iGPU host re-ran host detection and routed back to the crashing Vulkan
bundle (#7213). Record install_kind in the prebuilt marker and re-assert
--cpu-fallback on update when the installed bundle is CPU.

Also make setup.sh's UNSLOTH_LLAMA_CPP_BACKEND check case-insensitive to match
setup.ps1, and add tests for the updater CPU preservation and the setup.sh flag
plumbing.

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Trim and validate UNSLOTH_LLAMA_CPP_BACKEND, warn on unknown values for PR #7228

Trim surrounding whitespace and lowercase the value in both setup.sh and
setup.ps1, so values like ' cpu ' or 'CPU' still force the CPU-only prebuilt.
An unrecognized value (e.g. 'gpu') now prints a warning instead of silently
falling back to auto. Extend test_setup_llama_cpp_backend.py to cover both
scripts, including trimmed, empty and unknown values.

* Preserve arm64 CPU installs on update and honor CPU override in Windows prune for PR #7228

The update-path CPU preservation only matched install_kind ending in -cpu, so
arm64 CPU bundles (linux-arm64, windows-arm64) were re-routed to a GPU or source
build on update. Match the full set of CPU-only kinds instead.

Persisting install_kind also activated the previously inert Windows
mismatch-prune in setup.ps1: on a GPU host with UNSLOTH_LLAMA_CPP_BACKEND=cpu it
saw the windows-cpu marker as mismatched and deleted it every rerun. Normalize
the override once and make CPU expected so a deliberate CPU install is kept.
Extend the tests to cover both.

* Document legacy llama.cpp markers keep heal-to-GPU on update for PR #7228

Legacy prebuilt markers written before install_kind was persisted intentionally
do not force --cpu-fallback on update: the in-app updater lets them re-resolve
(heal to a GPU bundle) per the existing behavior from #6097, and only markers
that explicitly record a CPU install_kind are pinned to CPU. Add a comment and a
regression case documenting the boundary.

* Tighten llama.cpp CPU-fallback comments for PR #7228

* Fix Windows install-prune to keep valid Intel/fallback bundles for PR #7228

Persisting install_kind activated the setup.ps1 mismatch-prune, whose
expectedKinds was incomplete: the non-NVIDIA/non-AMD branch omitted
windows-vulkan (the Intel auto-route) and the GPU branches omitted the
windows-cpu/windows-arm64 fallback the installer uses when a GPU prebuilt is
missing. That made every setup rerun delete and re-download a valid Intel Vulkan
(or CPU-fallback) install. List all kinds the installer can produce per host so
only a bundle the host cannot run is pruned. Cover the full matrix in tests.

* Persist force_cpu marker flag so only forced CPU installs re-assert on update for PR #7228

* Add --force-cpu for deliberate CPU installs and warn on macOS for PR #7228

* Record force_cpu when reusing a matching CPU bundle for PR #7228

* Accept force_cpu keyword in installer test validator fakes for PR #7228

---------

Co-authored-by: danielhanchen <unslothai@gmail.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Daniel Han <danielhanchen@gmail.com>
2026-07-20 00:33:56 -07:00
..
datasets Replace standalone Studio wording with Unsloth (#7221) 2026-07-19 00:47:04 -07:00
hardware Replace standalone Studio wording with Unsloth (#7221) 2026-07-19 00:47:04 -07:00
inference Reduce and tighten code comments and docstrings repo-wide (#6095) 2026-06-08 23:09:51 -07:00
models Studio: GPU memory configuration for GGUF models (#6414) 2026-07-19 05:46:22 -07:00
paths persist llama.cpp KV cache across idle auto-unload (slot save/restore) (#7204) 2026-07-20 00:12:42 -07:00
security Studio: persistent per-user trust_remote_code approval cache (#6551) 2026-06-22 05:12:49 -07:00
.gitkeep root studio folder 2026-02-02 09:13:49 +00:00
__init__.py Final cleanup 2026-03-12 18:28:04 +00:00
_studio_release_build.py Replace standalone Studio wording with Unsloth (#7221) 2026-07-19 00:47:04 -07:00
api_errors.py Replace standalone Studio wording with Unsloth (#7221) 2026-07-19 00:47:04 -07:00
cache_cleanup.py Reduce and tighten code comments and docstrings repo-wide (#6095) 2026-06-08 23:09:51 -07:00
client_ip.py Replace standalone Studio wording with Unsloth (#7221) 2026-07-19 00:47:04 -07:00
coding_agents.py feat: detect installed coding agent CLIs in Studio settings (#6909) 2026-07-08 05:26:50 -07:00
cpu_threads.py Replace standalone Studio wording with Unsloth (#7221) 2026-07-19 00:47:04 -07:00
downsample.py Formatting: ruff line-length 100, kwarg-spacing passes, drop blank after short local imports (#6079) 2026-06-08 04:24:13 -07:00
embedding_model_settings.py Studio: customizable RAG embedding model with HF search, settings tab reorganization (#6800) 2026-07-02 05:26:33 -07:00
helper_precache_settings.py Replace standalone Studio wording with Unsloth (#7221) 2026-07-19 00:47:04 -07:00
hf_xet_fallback.py Replace standalone Studio wording with Unsloth (#7221) 2026-07-19 00:47:04 -07:00
hidden_models.py Studio: hide the RAG embedder and llama.cpp probe from the hub cached inventory (#7018) 2026-07-19 03:20:56 -07:00
host_policy.py Replace standalone Studio wording with Unsloth (#7221) 2026-07-19 00:47:04 -07:00
lifespan_shutdown.py Studio: make lifespan shutdown resilient to a dead default executor (#6307) 2026-06-15 22:51:46 -07:00
llama_cpp_freshness.py Studio: stop the llama.cpp update banner flickering and show the download size (#6338) 2026-06-17 21:28:54 -07:00
llama_cpp_update.py feat(studio): add UNSLOTH_LLAMA_CPP_BACKEND env var to force CPU fallback #7213 (#7228) 2026-07-20 00:33:56 -07:00
mlx_repair.py Replace standalone Studio wording with Unsloth (#7221) 2026-07-19 00:47:04 -07:00
native_path_leases.py Reap Studio child processes when the parent dies abnormally (#6425) 2026-06-18 05:51:22 -07:00
node_runtime.py Studio: use an isolated Node.js for the frontend build instead of replacing the system Node/npm (#6533) 2026-06-21 21:17:29 -07:00
openai_auto_switch_settings.py persist llama.cpp KV cache across idle auto-unload (slot save/restore) (#7204) 2026-07-20 00:12:42 -07:00
personalization_settings.py studio: persist personalization (profile, avatar, theme) server-side (#6516) 2026-06-22 04:09:48 -07:00
preview_rate_limit.py Replace standalone Studio wording with Unsloth (#7221) 2026-07-19 00:47:04 -07:00
preview_sharing_settings.py Studio: require signed capability tokens for /p preview links (#6666) 2026-06-25 21:40:48 -07:00
preview_token.py Studio: require signed capability tokens for /p preview links (#6666) 2026-06-25 21:40:48 -07:00
process_lifetime.py Replace standalone Studio wording with Unsloth (#7221) 2026-07-19 00:47:04 -07:00
ssm_runtime.py Auto-install SSM kernels (causal-conv1d, mamba-ssm) for inference loads (#6535) 2026-06-22 04:48:29 -07:00
studio_version.py Replace standalone Studio wording with Unsloth (#7221) 2026-07-19 00:47:04 -07:00
subprocess_compat.py Reduce and tighten code comments and docstrings repo-wide (#6095) 2026-06-08 23:09:51 -07:00
training_runs.py Replace standalone Studio wording with Unsloth (#7221) 2026-07-19 00:47:04 -07:00
transformers_dtype.py Studio: Fix torch_dtype deprecation warning on startup and ASR load (#6999) 2026-07-13 17:34:25 -03:00
transformers_latest.py Replace standalone Studio wording with Unsloth (#7221) 2026-07-19 00:47:04 -07:00
transformers_version.py Replace standalone Studio wording with Unsloth (#7221) 2026-07-19 00:47:04 -07:00
update_status.py Studio: make code comments and docstrings more succinct (#6029) 2026-06-08 23:07:28 -07:00
upload_limits.py Replace standalone Studio wording with Unsloth (#7221) 2026-07-19 00:47:04 -07:00
utils.py Reduce and tighten code comments and docstrings repo-wide (#6095) 2026-06-08 23:09:51 -07:00
uv_path_safety.py Make _uv_safe_path space-safe on macOS/Linux (#6503) (#6534) 2026-06-24 04:02:24 -07:00
wheel_utils.py Studio: fix flash-attn and torchao install on Blackwell (sm_100+) GPUs (Closes #6961) (#6970) 2026-07-08 06:38:10 -07:00