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.

Desktop: offer a chat-only (GGUF) install and keep it through repairs (#14245)

Daniel Han3ceb60660f23
diff --git a/studio/backend/tests/test_chat_only_reason.py b/studio/backend/tests/test_chat_only_reason.py
index 49b09dd9841..ce136c5521c 100644
--- a/studio/backend/tests/test_chat_only_reason.py
+++ b/studio/backend/tests/test_chat_only_reason.py
@@ -76,6 +76,24 @@ def _no_torch_apple_silicon(monkeypatch, *, mlx_on_disk: bool):
monkeypatch.setattr(hw, "_has_usable_mlx_stack", lambda: False)
+def test_a_no_torch_install_off_mac_is_off_by_request_not_missing_a_gpu(monkeypatch):
+ # A chat-only Windows / Linux install on a GPU host: "needs an NVIDIA or AMD GPU" is wrong.
+ monkeypatch.setattr(hw, "is_apple_silicon", lambda: False)
+ monkeypatch.setattr(hw.platform, "system", lambda: "Windows")
+ monkeypatch.setattr(hw, "_installed_without_torch", lambda: True)
+ assert hw.detect_hardware() == hw.DeviceType.CPU
+ assert hw.CHAT_ONLY is True
+ assert hw.CHAT_ONLY_REASON == "no_torch"
+ assert hw.current_chat_only_verdict() == ("no_torch", None)
+
+
+def test_a_torch_install_off_mac_without_an_accelerator_stays_no_gpu(monkeypatch):
+ monkeypatch.setattr(hw, "is_apple_silicon", lambda: False)
+ monkeypatch.setattr(hw.platform, "system", lambda: "Linux")
+ hw.detect_hardware()
+ assert hw.CHAT_ONLY_REASON == "no_gpu"
+
+
def test_apple_silicon_no_torch_install_without_mlx_is_off_by_request(monkeypatch):
# GGUF-only by request: not a broken stack, so the UI must not send the user to
# `unsloth studio update`, which keeps no-torch and cannot enable Train.
diff --git a/studio/backend/utils/hardware/hardware.py b/studio/backend/utils/hardware/hardware.py
index e28c622289f..937d0129a67 100644
--- a/studio/backend/utils/hardware/hardware.py
+++ b/studio/backend/utils/hardware/hardware.py
@@ -1674,6 +1674,9 @@ def _detect_hardware_locked() -> DeviceType:
"with UNSLOTH_FORCE_ROCM_TORCH=1.",
os.environ.get("CUDA_VISIBLE_DEVICES"),
)
+ elif _installed_without_torch():
+ # GGUF-only by request: "needs a GPU" is wrong on a GPU host and nothing is broken.
+ CHAT_ONLY_REASON = "no_torch"
print("Hardware detected: CPU training backend (no PyTorch/MLX GPU backend available)")
return DEVICE
diff --git a/studio/frontend/scripts/check-bundle-budget.ts b/studio/frontend/scripts/check-bundle-budget.ts
index eaf614ce106..c5b13916952 100644
--- a/studio/frontend/scripts/check-bundle-budget.ts
+++ b/studio/frontend/scripts/check-bundle-budget.ts
@@ -295,8 +295,11 @@ export const BUDGET = {
// 2,061,092 B transfer against ad2fc0659c, one machine and build, Node 24, 96 chunks): switch.tsx is a shared UI
// primitive the startup set already carries. #14329 removed 163 B raw just before. Raised to that build plus the
// same 160 B raw / 189 B transfer margin.
- transferBytes: 2_061_281,
- rawBytes: 6_845_068,
+ // The Desktop chat-only install choice (#14245) adds 679 B raw / 205 B transfer (6,842,169 -> 6,842,848 B raw,
+ // 2,060,319 -> 2,060,524 B transfer against 26e246d407, one machine and build, Node 24, 96 chunks): the
+ // first-run checkbox lives in the eager startup screen and the Train hint in the eager sidebar. Raised by that.
+ transferBytes: 2_061_486,
+ rawBytes: 6_845_747,
};
// The chunk count is reported but not budgeted. Splitting a page out of the entry raises it while lowering the
diff --git a/studio/frontend/src/components/app-sidebar.tsx b/studio/frontend/src/components/app-sidebar.tsx
index 0bad65cbd77..0763128a447 100644
--- a/studio/frontend/src/components/app-sidebar.tsx
+++ b/studio/frontend/src/components/app-sidebar.tsx
@@ -92,6 +92,7 @@ import { cn } from "@/lib/utils";
import { createNavigationNonce } from "@/lib/navigation-nonce";
import { copyToClipboardFrom } from "@/lib/copy-to-clipboard";
import { isTauri } from "@/lib/api-base";
+import { useTauriRepairController } from "@/hooks/tauri-repair-context";
import { useWebUpdateCheck } from "@/hooks/use-web-update-check";
import { useUiSpaceScale } from "@/hooks/use-ui-space-scale";
import { useHoverFlyout } from "@/hooks/use-hover-flyout";
@@ -1311,6 +1312,9 @@ export function AppSidebar() {
const chatOnlyDetail = usePlatformStore((s) => s.chatOnlyDetail);
const chatOnlyHint = usePlatformStore((s) => s.chatOnlyHint);
const detectionDeferred = usePlatformStore((s) => s.detectionDeferred);
+ // Null off Desktop; an attached terminal-started backend has no Repair action to point at.
+ const repair = useTauriRepairController();
+ const canRepair = repair !== null && !repair.isExternalServer;
// Until /api/health answers, `chatOnly` is the browser-platform guess, so every Mac painted
// Train and Video blacked out on load and only recovered once the backend reported. Gate the
// rows on a measured verdict and let them spin until it lands.
@@ -1329,8 +1333,11 @@ export function AppSidebar() {
? `Training needs MLX: ${chatOnlyDetail}. Run \`unsloth studio update\` to enable Train.`
: "Training needs MLX. Run `unsloth studio update` to enable Train."
: chatOnlyReason === "no_torch"
- ? // GGUF-only by request. `unsloth studio update` keeps no-torch, so it is not the fix.
- "Training was left out of this install (--no-torch). Reinstall without --no-torch to enable Train."
+ ? // GGUF-only by request. `unsloth studio update` keeps no-torch, so it is not the fix;
+ // on Desktop the manual repair reruns the installer with PyTorch.
+ canRepair
+ ? "Training was left out of this install (Chat only). Use Repair installation in Settings to add it."
+ : "Training was left out of this install (--no-torch). Reinstall without --no-torch to enable Train."
: chatOnlyReason === "intel_mac"
? "Training needs Apple Silicon or a GPU. Intel Macs are chat-only."
: chatOnlyReason === "torch_cpu_build" ||
diff --git a/studio/frontend/src/components/tauri/startup-screen.tsx b/studio/frontend/src/components/tauri/startup-screen.tsx
index 515f3955471..a675cb9855f 100644
--- a/studio/frontend/src/components/tauri/startup-screen.tsx
+++ b/studio/frontend/src/components/tauri/startup-screen.tsx
@@ -11,6 +11,8 @@ import {
type StartupMessage,
} from "@/components/tauri/startup-messages";
import { Button } from "@/components/ui/button";
+import { Checkbox } from "@/components/ui/checkbox";
+import { Label } from "@/components/ui/label";
import { Spinner } from "@/components/ui/spinner";
import type { BackendStatus } from "@/hooks/use-tauri-backend";
import { useDocumentFlag } from "@/lib/document-flag";
@@ -83,7 +85,7 @@ function CheckingContent() {
);
}
-type InstallOptions = { skipLongPaths?: boolean };
+type InstallOptions = { skipLongPaths?: boolean; chatOnly?: boolean };
function NotInstalledContent({
onInstall,
@@ -93,6 +95,7 @@ function NotInstalledContent({
const [phase, setPhase] = useState<
"idle" | "checking" | "explain" | "elevating"
>("idle");
+ const [chatOnly, setChatOnly] = useState(false);
// Synchronous: a double click lands before the re-render that disables the buttons.
const busy = useRef(false);
@@ -107,7 +110,7 @@ function NotInstalledContent({
busy.current = false;
setPhase("explain");
} else {
- onInstall();
+ onInstall({ chatOnly });
}
}
@@ -119,7 +122,7 @@ function NotInstalledContent({
setPhase("elevating");
const outcome = await enableWindowsLongPaths();
// "failed" leaves setup.ps1's own UAC as the fallback.
- onInstall({ skipLongPaths: outcome === "declined" });
+ onInstall({ skipLongPaths: outcome === "declined", chatOnly });
}
function skipLongPaths() {
@@ -127,7 +130,7 @@ function NotInstalledContent({
return;
}
busy.current = true;
- onInstall({ skipLongPaths: true });
+ onInstall({ skipLongPaths: true, chatOnly });
}
if (phase === "explain" || phase === "elevating") {
@@ -159,6 +162,20 @@ function NotInstalledContent({
>
Get Started
</Button>
+ <div className="flex items-center gap-2">
+ <Checkbox
+ id="install-chat-only"
+ checked={chatOnly}
+ disabled={phase !== "idle"}
+ onCheckedChange={(checked) => setChatOnly(checked === true)}
+ />
+ <Label
+ htmlFor="install-chat-only"
+ className="text-ui-12 font-normal text-muted-foreground"
+ >
+ Chat only (GGUF): smaller install, no training
+ </Label>
+ </div>
<InstallLocation disabled={phase !== "idle"} />
</div>
</div>
diff --git a/studio/frontend/src/hooks/use-tauri-backend.ts b/studio/frontend/src/hooks/use-tauri-backend.ts
index 8ebadec21cd..22ca001b1f6 100644
--- a/studio/frontend/src/hooks/use-tauri-backend.ts
+++ b/studio/frontend/src/hooks/use-tauri-backend.ts
@@ -183,6 +183,7 @@ export function useTauriBackend() {
const environmentWaitPollsRef = useRef(0);
const authFailureRef = useRef<string | null>(getTauriAuthFailure());
const elevationResumeRef = useRef<"install" | "repair" | null>(null);
+ const chatOnlyRef = useRef(false);
// Whether the repair in flight was asked to skip straight to the installer. Read back by
// approveElevation, which restarts the repair after the system packages land.
const forcedRepairRef = useRef(false);
@@ -571,8 +572,13 @@ export function useTauriBackend() {
}
// Strict check: onClick passes a click event here.
- async function startInstall(options?: { skipLongPaths?: boolean }) {
+ async function startInstall(options?: { skipLongPaths?: boolean; chatOnly?: boolean }) {
const skipLongPaths = options?.skipLongPaths === true;
+ // Kept for the Linux elevation resume, which restarts the install without options.
+ if (options) {
+ chatOnlyRef.current = options.chatOnly === true;
+ }
+ const chatOnly = chatOnlyRef.current;
elevationResumeRef.current = null;
setCurrentStepIndex(-1);
setProgressDetail(null);
@@ -582,7 +588,7 @@ export function useTauriBackend() {
clearBackendError();
const { invoke } = await import("@tauri-apps/api/core");
try {
- await invoke("start_install", { skipLongPaths });
+ await invoke("start_install", { skipLongPaths, chatOnly });
// Install done: start the managed backend we just installed. Don't run the general preflight
// here, it can attach to an unrelated running CLI/backend before launching ours. The
// install-complete listener does NOT call startServer() to avoid a double-start race.
diff --git a/studio/frontend/tests/install-disk-full-flag.test.ts b/studio/frontend/tests/install-disk-full-flag.test.ts
index 1caad8c46d9..3bcbeb8029f 100644
--- a/studio/frontend/tests/install-disk-full-flag.test.ts
+++ b/studio/frontend/tests/install-disk-full-flag.test.ts
@@ -49,6 +49,7 @@ async function failInstall(order: "event-first" | "reject-first") {
authFailureRef: { current: null },
statusRef: { current: "not-installed" },
elevationResumeRef: { current: null },
+ chatOnlyRef: { current: false },
seenStepsRef: { current: new Set() },
stopManagedEnvironmentWait: noop,
syncTrayStatus: noop,
@@ -110,11 +111,15 @@ ${installBody
return state;
}
-async function installArgs(options: unknown): Promise<unknown> {
+async function installArgs(
+ options: unknown,
+ chatOnlyRef = { current: false },
+): Promise<unknown> {
let args: unknown;
const noop = () => {};
const scope: Record<string, unknown> = {
elevationResumeRef: { current: null },
+ chatOnlyRef,
seenStepsRef: { current: new Set() },
statusRef: { current: "not-installed" },
setCurrentStepIndex: noop,
@@ -147,10 +152,30 @@ ${installBody
}
test("a skipped Long Paths explainer reaches start_install", async () => {
- assert.deepEqual(await installArgs({ skipLongPaths: true }), { skipLongPaths: true });
- assert.deepEqual(await installArgs(undefined), { skipLongPaths: false });
+ assert.deepEqual(await installArgs({ skipLongPaths: true }), {
+ skipLongPaths: true,
+ chatOnly: false,
+ });
+ assert.deepEqual(await installArgs(undefined), { skipLongPaths: false, chatOnly: false });
assert.deepEqual(await installArgs({ type: "click", skipLongPaths: "x" }), {
skipLongPaths: false,
+ chatOnly: false,
+ });
+});
+
+test("a chat-only choice reaches start_install and survives the elevation resume", async () => {
+ const chatOnlyRef = { current: false };
+ assert.deepEqual(await installArgs({ chatOnly: true }, chatOnlyRef), {
+ skipLongPaths: false,
+ chatOnly: true,
+ });
+ assert.deepEqual(await installArgs(undefined, chatOnlyRef), {
+ skipLongPaths: false,
+ chatOnly: true,
+ });
+ assert.deepEqual(await installArgs({ chatOnly: false }, chatOnlyRef), {
+ skipLongPaths: false,
+ chatOnly: false,
});
});
diff --git a/studio/src-tauri/src/commands.rs b/studio/src-tauri/src/commands.rs
index 35ea362a800..16451782f0b 100644
--- a/studio/src-tauri/src/commands.rs
+++ b/studio/src-tauri/src/commands.rs
@@ -890,6 +890,7 @@ pub async fn start_install(
update_state: tauri::State<'_, update::UpdateState>,
diagnostics: tauri::State<'_, DiagnosticsState>,
skip_long_paths: Option<bool>,
+ chat_only: Option<bool>,
) -> Result<(), String> {
if has_owned_backend(&backend_state)? {
return Err(
@@ -906,8 +907,9 @@ pub async fn start_install(
let state = state.inner().clone();
let diagnostics_state = diagnostics.inner().clone();
let skip_long_paths = skip_long_paths.unwrap_or(false);
+ let no_torch = chat_only.unwrap_or(false);
tokio::task::spawn_blocking(move || {
- install::run_install(app, state, diagnostics_state, skip_long_paths)
+ install::run_install(app, state, diagnostics_state, skip_long_paths, no_torch)
})
.await
.map_err(|e| format!("Install task panicked: {e}"))?
diff --git a/studio/src-tauri/src/install.rs b/studio/src-tauri/src/install.rs
index 94fd9d4958a..4d829d929a2 100644
--- a/studio/src-tauri/src/install.rs
+++ b/studio/src-tauri/src/install.rs
@@ -953,10 +953,12 @@ pub fn run_install(
state: InstallState,
diagnostics: DiagnosticsState,
skip_long_paths: bool,
+ no_torch: bool,
) -> Result<(), String> {
let env = InstallerEnv {
upgrade_torch: false,
skip_long_paths,
+ no_torch,
};
run_install_with_event_mode(app, state, diagnostics, InstallEventMode::Full, None, env)
}
@@ -980,6 +982,10 @@ pub(crate) fn run_install_for_repair(
InstallerEnv {
upgrade_torch,
skip_long_paths: false,
+ // The installers read the mode from the environment only; the manual repair is the
+ // user asking for PyTorch back (its dialog says so).
+ no_torch: !upgrade_torch
+ && crate::studio_home::studio_root().is_some_and(|root| recorded_no_torch(&root)),
},
)
}
@@ -988,6 +994,19 @@ pub(crate) fn run_install_for_repair(
struct InstallerEnv {
upgrade_torch: bool,
skip_long_paths: bool,
+ no_torch: bool,
+}
+
+/// Whether the managed venv under `root` was installed GGUF-only. Mirrors
+/// install_manifest.recorded_no_torch: the manifest key wins, the marker answers only when
+/// the manifest is missing (an interrupted pass) or predates the key.
+fn recorded_no_torch(root: &Path) -> bool {
+ let venv = root.join("unsloth_studio");
+ let recorded = std::fs::read_to_string(venv.join("unsloth_install_manifest.json"))
+ .ok()
+ .and_then(|text| serde_json::from_str::<serde_json::Value>(&text).ok())
+ .and_then(|manifest| manifest.get("no_torch").and_then(|v| v.as_bool()));
+ recorded.unwrap_or_else(|| venv.join(".unsloth-no-torch").is_file())
}
/// Extra environment for the installer child. UNSLOTH_TORCH_UPGRADE=1 is install.sh's and
@@ -1001,6 +1020,8 @@ fn installer_env(env: InstallerEnv) -> Vec<(&'static str, &'static str)> {
if env.skip_long_paths {
vars.push(("UNSLOTH_SKIP_LONG_PATHS", "1"));
}
+ // Always set, so an UNSLOTH_NO_TORCH inherited by the app cannot override the choice.
+ vars.push(("UNSLOTH_NO_TORCH", if env.no_torch { "1" } else { "0" }));
vars
}
@@ -1691,8 +1712,14 @@ mod tests {
upgrade_torch: true,
..Default::default()
};
- assert_eq!(installer_env(upgrade), vec![("UNSLOTH_TORCH_UPGRADE", "1")]);
- assert!(installer_env(InstallerEnv::default()).is_empty());
+ assert_eq!(
+ installer_env(upgrade),
+ vec![("UNSLOTH_TORCH_UPGRADE", "1"), ("UNSLOTH_NO_TORCH", "0")]
+ );
+ assert_eq!(
+ installer_env(InstallerEnv::default()),
+ vec![("UNSLOTH_NO_TORCH", "0")]
+ );
}
#[test]
@@ -1701,17 +1728,64 @@ mod tests {
skip_long_paths: true,
..Default::default()
};
- assert_eq!(installer_env(skip), vec![("UNSLOTH_SKIP_LONG_PATHS", "1")]);
+ assert_eq!(
+ installer_env(skip),
+ vec![("UNSLOTH_SKIP_LONG_PATHS", "1"), ("UNSLOTH_NO_TORCH", "0")]
+ );
let both = InstallerEnv {
upgrade_torch: true,
skip_long_paths: true,
+ ..Default::default()
};
assert_eq!(
installer_env(both),
- vec![("UNSLOTH_TORCH_UPGRADE", "1"), ("UNSLOTH_SKIP_LONG_PATHS", "1")]
+ vec![
+ ("UNSLOTH_TORCH_UPGRADE", "1"),
+ ("UNSLOTH_SKIP_LONG_PATHS", "1"),
+ ("UNSLOTH_NO_TORCH", "0")
+ ]
);
}
+ #[test]
+ fn a_chat_only_install_reaches_the_installer_as_no_torch() {
+ let chat_only = InstallerEnv {
+ no_torch: true,
+ ..Default::default()
+ };
+ assert_eq!(installer_env(chat_only), vec![("UNSLOTH_NO_TORCH", "1")]);
+ }
+
+ #[test]
+ fn recorded_no_torch_reads_the_marker_then_the_manifest() {
+ let root = std::env::temp_dir().join(format!(
+ "unsloth-recorded-no-torch-{}-{:?}",
+ std::process::id(),
+ std::thread::current().id()
+ ));
+ let venv = root.join("unsloth_studio");
+ let _ = std::fs::remove_dir_all(&root);
+ assert!(!recorded_no_torch(&root));
+ std::fs::create_dir_all(&venv).unwrap();
+ assert!(!recorded_no_torch(&root));
+
+ let manifest = venv.join("unsloth_install_manifest.json");
+ std::fs::write(&manifest, r#"{"no_torch": false}"#).unwrap();
+ assert!(!recorded_no_torch(&root));
+ std::fs::write(&manifest, r#"{"no_torch": true}"#).unwrap();
+ assert!(recorded_no_torch(&root));
+ std::fs::write(&manifest, "not json").unwrap();
+ assert!(!recorded_no_torch(&root));
+
+ std::fs::write(venv.join(".unsloth-no-torch"), "").unwrap();
+ assert!(recorded_no_torch(&root));
+ std::fs::write(&manifest, "{}").unwrap();
+ assert!(recorded_no_torch(&root));
+ std::fs::write(&manifest, r#"{"no_torch": false}"#).unwrap();
+ assert!(!recorded_no_torch(&root));
+ let _ = std::fs::remove_dir_all(&root);
+ }
+
#[test]
fn repair_install_mode_uses_repair_elevation_event() {
assert_eq!(