+ {title ?
{title}
: null}
{hasProgress ? (
-
+
{progressLabel}
{Math.round(clampProgress(progressPercent))}%
@@ -36,18 +42,19 @@ export function ModelLoadDescription({
) : message ? (
-
{message}
+
{message}
) : null}
{onStop ? (
) : null}
diff --git a/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts b/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
index 6927b1871f..cfdd4e774a 100644
--- a/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
+++ b/studio/frontend/src/features/chat/hooks/use-chat-model-runtime.ts
@@ -3,7 +3,6 @@
import { createElement, useCallback, useRef, useState } from "react";
import { toast } from "sonner";
-import { Spinner } from "@/components/ui/spinner";
import { ModelLoadDescription } from "../components/model-load-status";
import {
getDownloadProgress,
@@ -34,12 +33,10 @@ type SelectedModelInput = {
};
const MODEL_LOAD_TOAST_CLASSNAMES = {
- toast: "items-start gap-2.5 pr-8",
- content: "gap-0.5",
+ toast: "items-start gap-2.5",
+ content: "gap-0.5 flex-1 min-w-0",
title: "leading-5",
- description: "mt-0",
- closeButton:
- "!left-auto !right-1.5 !top-1.5 !translate-x-0 !translate-y-0 !border-transparent !bg-transparent !shadow-none hover:!bg-transparent hover:opacity-70",
+ description: "mt-0 w-full",
} as const;
const LORA_SUFFIX_RE = /_(\d{9,})$/;
@@ -200,12 +197,14 @@ export function useChatModelRuntime() {
const renderLoadDescription = useCallback(
(
+ title: string,
message: string,
progressPercent?: number | null,
progressLabel?: string | null,
onStop?: () => void,
) =>
createElement(ModelLoadDescription, {
+ title,
message,
progressPercent,
progressLabel,
@@ -448,18 +447,19 @@ export function useChatModelRuntime() {
}
}
+ const toastTitle = isDownloaded ? "Starting modelβ¦" : "Downloading modelβ¦";
const toastId = toast(
- isDownloaded ? "Starting modelβ¦" : "Downloading modelβ¦",
+ null,
{
- icon: createElement(Spinner, { className: "size-4" }),
description: renderLoadDescription(
+ toastTitle,
loadingDescription,
isDownloaded ? null : 0,
isDownloaded ? null : "Preparing download",
cancelLoading,
),
duration: Infinity,
- closeButton: true,
+ closeButton: false,
classNames: MODEL_LOAD_TOAST_CLASSNAMES,
onDismiss: (dismissedToast) => {
if (loadToastIdRef.current !== dismissedToast.id) {
@@ -505,18 +505,18 @@ export function useChatModelRuntime() {
});
if (loadToastDismissedRef.current) return;
toast(
- "Downloading modelβ¦",
+ null,
{
id: toastId,
- icon: createElement(Spinner, { className: "size-4" }),
description: renderLoadDescription(
+ "Downloading modelβ¦",
loadingDescription,
pct,
progressLabel,
cancelLoading,
),
duration: Infinity,
- closeButton: true,
+ closeButton: false,
classNames: MODEL_LOAD_TOAST_CLASSNAMES,
onDismiss: (dismissedToast) => {
if (loadToastIdRef.current !== dismissedToast.id) return;
@@ -542,17 +542,17 @@ export function useChatModelRuntime() {
if (progressInterval) clearInterval(progressInterval);
return;
}
- toast("Starting modelβ¦", {
+ toast(null, {
id: toastId,
- icon: createElement(Spinner, { className: "size-4" }),
description: renderLoadDescription(
+ "Starting modelβ¦",
"Download complete. Loading the model into memory.",
100,
"Download complete",
cancelLoading,
),
duration: Infinity,
- closeButton: true,
+ closeButton: false,
classNames: MODEL_LOAD_TOAST_CLASSNAMES,
onDismiss: (dismissedToast) => {
if (loadToastIdRef.current !== dismissedToast.id) return;
diff --git a/studio/frontend/src/features/chat/shared-composer.tsx b/studio/frontend/src/features/chat/shared-composer.tsx
index c2ca25a658..89b65d4d99 100644
--- a/studio/frontend/src/features/chat/shared-composer.tsx
+++ b/studio/frontend/src/features/chat/shared-composer.tsx
@@ -363,8 +363,8 @@ export function SharedComposer({
// Side 1: load β generate β wait
if (handle1 && model1?.id) {
toast("Loading Model 1β¦", { id: toastId, description: name1, duration: Infinity });
- await ensureModelLoaded(model1);
- toast("Generating with Model 1β¦", { id: toastId, description: name1, duration: Infinity });
+ const status1 = await ensureModelLoaded(model1);
+ toast("Generating with Model 1β¦", { id: toastId, description: `${name1} (${status1})`, duration: Infinity });
const done = handle1.waitForRunEnd();
handle1.startRun();
await done;
@@ -377,8 +377,8 @@ export function SharedComposer({
if (needsLoad) {
toast("Loading Model 2β¦", { id: toastId, description: name2, duration: Infinity });
}
- await ensureModelLoaded(model2);
- toast("Generating with Model 2β¦", { id: toastId, description: name2, duration: Infinity });
+ const status2 = await ensureModelLoaded(model2);
+ toast("Generating with Model 2β¦", { id: toastId, description: `${name2} (${status2})`, duration: Infinity });
const done = handle2.waitForRunEnd();
handle2.startRun();
await done;
diff --git a/studio/frontend/src/features/chat/stores/chat-runtime-store.ts b/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
index 43736d6257..b7f222e3bf 100644
--- a/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
+++ b/studio/frontend/src/features/chat/stores/chat-runtime-store.ts
@@ -10,6 +10,9 @@ import {
} from "../types/runtime";
const AUTO_TITLE_KEY = "unsloth_chat_auto_title";
+const AUTO_HEAL_TOOL_CALLS_KEY = "unsloth_auto_heal_tool_calls";
+const MAX_TOOL_CALLS_KEY = "unsloth_max_tool_calls_per_message";
+const TOOL_CALL_TIMEOUT_KEY = "unsloth_tool_call_timeout";
function canUseStorage(): boolean {
return typeof window !== "undefined";
@@ -35,6 +38,27 @@ function saveBool(key: string, value: boolean): void {
}
}
+function loadInt(key: string, fallback: number): number {
+ if (!canUseStorage()) return fallback;
+ try {
+ const raw = localStorage.getItem(key);
+ if (raw === null) return fallback;
+ const parsed = parseInt(raw, 10);
+ return Number.isNaN(parsed) ? fallback : parsed;
+ } catch {
+ return fallback;
+ }
+}
+
+function saveInt(key: string, value: number): void {
+ if (!canUseStorage()) return;
+ try {
+ localStorage.setItem(key, String(value));
+ } catch {
+ // ignore
+ }
+}
+
type ChatRuntimeStore = {
params: InferenceParams;
models: ChatModelSummary[];
@@ -51,6 +75,9 @@ type ChatRuntimeStore = {
codeToolsEnabled: boolean;
toolStatus: string | null;
generatingStatus: string | null;
+ autoHealToolCalls: boolean;
+ maxToolCallsPerMessage: number;
+ toolCallTimeout: number;
kvCacheDtype: string | null;
defaultChatTemplate: string | null;
chatTemplateOverride: string | null;
@@ -73,6 +100,9 @@ type ChatRuntimeStore = {
setCodeToolsEnabled: (enabled: boolean) => void;
setToolStatus: (status: string | null) => void;
setGeneratingStatus: (status: string | null) => void;
+ setAutoHealToolCalls: (enabled: boolean) => void;
+ setMaxToolCallsPerMessage: (value: number) => void;
+ setToolCallTimeout: (value: number) => void;
setKvCacheDtype: (dtype: string | null) => void;
setChatTemplateOverride: (template: string | null) => void;
setPendingAudio: (base64: string, name: string) => void;
@@ -95,6 +125,9 @@ export const useChatRuntimeStore = create
((set) => ({
codeToolsEnabled: false,
toolStatus: null,
generatingStatus: null,
+ autoHealToolCalls: loadBool(AUTO_HEAL_TOOL_CALLS_KEY, true),
+ maxToolCallsPerMessage: loadInt(MAX_TOOL_CALLS_KEY, 10),
+ toolCallTimeout: loadInt(TOOL_CALL_TIMEOUT_KEY, 5),
kvCacheDtype: null,
defaultChatTemplate: null,
chatTemplateOverride: null,
@@ -154,6 +187,21 @@ export const useChatRuntimeStore = create((set) => ({
setCodeToolsEnabled: (codeToolsEnabled) => set({ codeToolsEnabled }),
setToolStatus: (toolStatus) => set({ toolStatus }),
setGeneratingStatus: (generatingStatus) => set({ generatingStatus }),
+ setAutoHealToolCalls: (autoHealToolCalls) =>
+ set(() => {
+ saveBool(AUTO_HEAL_TOOL_CALLS_KEY, autoHealToolCalls);
+ return { autoHealToolCalls };
+ }),
+ setMaxToolCallsPerMessage: (maxToolCallsPerMessage) =>
+ set(() => {
+ saveInt(MAX_TOOL_CALLS_KEY, maxToolCallsPerMessage);
+ return { maxToolCallsPerMessage };
+ }),
+ setToolCallTimeout: (toolCallTimeout) =>
+ set(() => {
+ saveInt(TOOL_CALL_TIMEOUT_KEY, toolCallTimeout);
+ return { toolCallTimeout };
+ }),
setKvCacheDtype: (kvCacheDtype) => set({ kvCacheDtype }),
setChatTemplateOverride: (chatTemplateOverride) => set({ chatTemplateOverride }),
setPendingAudio: (base64, name) =>
diff --git a/studio/frontend/src/features/chat/types/api.ts b/studio/frontend/src/features/chat/types/api.ts
index a7be85766e..013e658105 100644
--- a/studio/frontend/src/features/chat/types/api.ts
+++ b/studio/frontend/src/features/chat/types/api.ts
@@ -156,6 +156,11 @@ export interface OpenAIChatCompletionsRequest {
use_adapter?: boolean | string | null;
enable_thinking?: boolean | null;
enable_tools?: boolean | null;
+ enabled_tools?: string[];
+ auto_heal_tool_calls?: boolean;
+ max_tool_calls_per_message?: number;
+ tool_call_timeout?: number;
+ session_id?: string;
}
export interface OpenAIChatDelta {
diff --git a/studio/frontend/src/features/studio/sections/dataset-section.tsx b/studio/frontend/src/features/studio/sections/dataset-section.tsx
index ab05d8e70b..7538fb1379 100644
--- a/studio/frontend/src/features/studio/sections/dataset-section.tsx
+++ b/studio/frontend/src/features/studio/sections/dataset-section.tsx
@@ -310,8 +310,8 @@ export function DatasetSection() {
if (datasetSource !== "upload") return;
if (!uploadedFile) return;
if (selectedLocalDataset) return;
- // Don't clear if this is a direct file upload (not a recipe directory)
- if (isLikelyLocalDatasetRef(uploadedFile)) return;
+ // Don't clear if this is a direct file upload (e.g. user uploaded a .jsonl/.csv)
+ if (/\.(jsonl|json|csv|parquet|arrow)$/i.test(uploadedFile)) return;
selectLocalDataset(null);
}, [
datasetSource,
diff --git a/studio/frontend/src/features/studio/sections/model-section.tsx b/studio/frontend/src/features/studio/sections/model-section.tsx
index 77edf68d24..e9bcde17b5 100644
--- a/studio/frontend/src/features/studio/sections/model-section.tsx
+++ b/studio/frontend/src/features/studio/sections/model-section.tsx
@@ -372,7 +372,7 @@ export function ModelSection() {
- Base Model
+ Hugging Face Model
-
+
+ {
+ if (v && trySetContextLength(v)) {
+ setCtxInput(v);
+ }
+ }}
+ onInputValueChange={setCtxInput}
+ itemToStringValue={(id) => Number(id).toLocaleString()}
+ autoHighlight={false}
+ >
+ {
+ trySetContextLength(ctxInput);
+ setCtxInput(String(store.contextLength));
+ }}
+ onKeyDown={(e) => {
+ if (e.key !== "Enter") { return; }
+ const n = trySetContextLength(ctxInput);
+ if (n === null) { return; }
+ if (!ctxItems.includes(ctxInput.trim())) {
+ e.stopPropagation();
+ e.preventDefault();
+ }
+ setCtxInput(String(n));
+ }}
+ />
+
+ Enter a custom value
+
+ {(id: string) => (
+
+ {Number(id).toLocaleString()}
+
+ )}
+
+
+
+
Max sequence length for training samples
diff --git a/studio/frontend/src/features/studio/tour/steps/base-model.tsx b/studio/frontend/src/features/studio/tour/steps/base-model.tsx
index 70f49c58b8..f047520a94 100644
--- a/studio/frontend/src/features/studio/tour/steps/base-model.tsx
+++ b/studio/frontend/src/features/studio/tour/steps/base-model.tsx
@@ -6,7 +6,7 @@ import { ReadMore, type TourStep } from "@/features/tour";
export const studioBaseModelStep: TourStep = {
id: "base-model",
target: "studio-base-model",
- title: "Base model from Hugging Face",
+ title: "Hugging Face Model",
body: (
<>
Paste
org/model or search. Pick a base
diff --git a/studio/frontend/src/index.css b/studio/frontend/src/index.css
index 397853a7b7..307bf36819 100644
--- a/studio/frontend/src/index.css
+++ b/studio/frontend/src/index.css
@@ -157,7 +157,6 @@
--shadow-2xl: 0px 0px 0px 0px hsl(0 0% 0% / 0);
}
-
@theme inline {
--font-sans: "Inter Variable", ui-sans-serif, sans-serif, system-ui;
--font-heading: "Hellix", "Space Grotesk Variable", ui-sans-serif, sans-serif;
@@ -325,8 +324,22 @@
[data-streamdown="list-item"] {
display: list-item;
}
-}
+ /* Flatten code blocks: single border, language label, then code directly */
+ [data-streamdown="code-block-body"] {
+ border: none !important;
+ border-radius: 0 !important;
+ background: transparent !important;
+ padding: 0 !important;
+ }
+ [data-streamdown="code-block"] {
+ gap: 0;
+ padding: 0.5rem;
+ }
+ [data-streamdown="code-block-header"] {
+ padding-left: 0.75rem;
+ }
+}
/* Minimal scrollbar β thumb only, no track */
* {
@@ -373,4 +386,4 @@
::view-transition-old(root), ::view-transition-new(root) {
animation: none;
mix-blend-mode: normal;
-}
+}
\ No newline at end of file
diff --git a/studio/frontend/tsconfig.app.json b/studio/frontend/tsconfig.app.json
index 216210eacd..33b2035b9a 100644
--- a/studio/frontend/tsconfig.app.json
+++ b/studio/frontend/tsconfig.app.json
@@ -18,7 +18,7 @@
/* Linting */
"strict": true,
- "noUnusedLocals": true,
+ "noUnusedLocals": false,
"noUnusedParameters": true,
"erasableSyntaxOnly": true,
"noFallthroughCasesInSwitch": true,
diff --git a/studio/install_python_stack.py b/studio/install_python_stack.py
index 20011a298a..a141c64425 100644
--- a/studio/install_python_stack.py
+++ b/studio/install_python_stack.py
@@ -140,15 +140,15 @@ def _bootstrap_uv() -> bool:
global UV_NEEDS_SYSTEM
if not shutil.which("uv"):
return False
- # Probe: try a dry-run install without --system.
- # If uv can't find a venv it exits with code 2.
+ # Probe: try a dry-run install targeting the current Python explicitly.
+ # Without --python, uv can ignore the activated venv on some platforms.
probe = subprocess.run(
- ["uv", "pip", "install", "--dry-run", "pip"],
+ ["uv", "pip", "install", "--dry-run", "--python", sys.executable, "pip"],
stdout = subprocess.PIPE,
stderr = subprocess.STDOUT,
)
if probe.returncode != 0:
- # Retry with --system to confirm it works
+ # Retry with --system (some envs need it when uv can't find a venv)
probe_sys = subprocess.run(
["uv", "pip", "install", "--dry-run", "--system", "pip"],
stdout = subprocess.PIPE,
@@ -204,6 +204,10 @@ def _build_uv_cmd(args: tuple[str, ...]) -> list[str]:
cmd = ["uv", "pip", "install"]
if UV_NEEDS_SYSTEM:
cmd.append("--system")
+ # Always pass --python so uv targets the correct environment.
+ # Without this, uv can ignore an activated venv and install into
+ # the system Python (observed on Colab and similar environments).
+ cmd.extend(["--python", sys.executable])
cmd.extend(_translate_pip_args_for_uv(args))
cmd.append("--torch-backend=auto")
return cmd
diff --git a/studio/setup.ps1 b/studio/setup.ps1
index 2420448deb..c768c066af 100644
--- a/studio/setup.ps1
+++ b/studio/setup.ps1
@@ -8,7 +8,7 @@
Always installs Node.js if needed. When running from pip install:
skips frontend build (already bundled). When running from git repo:
full setup including frontend build.
- Requires an NVIDIA GPU -- CPU-only machines are not supported.
+ Supports NVIDIA GPU (full training + inference) and CPU-only (GGUF chat mode).
.NOTES
Usage: powershell -ExecutionPolicy Bypass -File setup.ps1
#>
@@ -107,11 +107,15 @@ function Find-Nvcc {
# Returns e.g. "80" for A100 (8.0), "89" for RTX 4090 (8.9), etc.
# Returns $null if detection fails.
function Get-CudaComputeCapability {
- $nvSmi = Get-Command nvidia-smi -ErrorAction SilentlyContinue
- if (-not $nvSmi) { return $null }
+ # Use the resolved absolute path ($NvidiaSmiExe) to survive Refresh-Environment
+ $smiExe = if ($script:NvidiaSmiExe) { $script:NvidiaSmiExe } else {
+ $cmd = Get-Command nvidia-smi -ErrorAction SilentlyContinue
+ if ($cmd) { $cmd.Source } else { $null }
+ }
+ if (-not $smiExe) { return $null }
try {
- $raw = & nvidia-smi --query-gpu=compute_cap --format=csv,noheader 2>$null
+ $raw = & $smiExe --query-gpu=compute_cap --format=csv,noheader 2>$null
if ($LASTEXITCODE -ne 0 -or -not $raw) { return $null }
# nvidia-smi may return multiple GPUs; take the first one
@@ -168,14 +172,17 @@ function Get-NvccMaxArch {
# https://download.pytorch.org/whl/
. The tag must not exceed the driver's
# capability: e.g. driver "CUDA Version: 12.9" β cu128 (not cu130).
function Get-PytorchCudaTag {
- $nvSmi = Get-Command nvidia-smi -ErrorAction SilentlyContinue
- if (-not $nvSmi) { return "cu124" }
+ $smiExe = if ($script:NvidiaSmiExe) { $script:NvidiaSmiExe } else {
+ $cmd = Get-Command nvidia-smi -ErrorAction SilentlyContinue
+ if ($cmd) { $cmd.Source } else { $null }
+ }
+ if (-not $smiExe) { return "cu124" }
try {
# 2>&1 | Out-String merges stderr into stdout then converts to a single
- # string. Plain 2>$null doesn't fully suppress stderr in PS 5.1 β
+ # string. Plain 2>$null doesn't fully suppress stderr in PS 5.1 --
# ErrorRecord objects leak into $output and break the -match.
- $output = & nvidia-smi 2>&1 | Out-String
+ $output = & $smiExe 2>&1 | Out-String
if ($output -match 'CUDA Version:\s+(\d+)\.(\d+)') {
$major = [int]$Matches[1]
$minor = [int]$Matches[2]
@@ -251,23 +258,50 @@ Write-Host "+==============================================+" -ForegroundColor G
# ==========================================================================
# ============================================
-# 1a. GPU requirement check
+# 1a. GPU detection
# ============================================
$HasNvidiaSmi = $false
+$NvidiaSmiExe = $null # Absolute path -- survives Refresh-Environment
try {
- nvidia-smi 2>&1 | Out-Null
- if ($LASTEXITCODE -eq 0) { $HasNvidiaSmi = $true }
+ $nvSmiCmd = Get-Command nvidia-smi -ErrorAction SilentlyContinue
+ if ($nvSmiCmd) {
+ & $nvSmiCmd.Source 2>&1 | Out-Null
+ if ($LASTEXITCODE -eq 0) {
+ $HasNvidiaSmi = $true
+ $NvidiaSmiExe = $nvSmiCmd.Source
+ }
+ }
} catch {}
+# Fallback: nvidia-smi may not be on PATH even though a GPU + driver exist.
+# Check the default install location and the Windows driver store.
+if (-not $HasNvidiaSmi) {
+ $nvSmiDefaults = @(
+ "$env:ProgramFiles\NVIDIA Corporation\NVSMI\nvidia-smi.exe",
+ "$env:SystemRoot\System32\nvidia-smi.exe"
+ )
+ foreach ($p in $nvSmiDefaults) {
+ if (Test-Path $p) {
+ try {
+ & $p 2>&1 | Out-Null
+ if ($LASTEXITCODE -eq 0) {
+ $HasNvidiaSmi = $true
+ $NvidiaSmiExe = $p
+ Write-Host " Found nvidia-smi at $(Split-Path $p -Parent)" -ForegroundColor Gray
+ break
+ }
+ } catch {}
+ }
+ }
+}
if (-not $HasNvidiaSmi) {
Write-Host ""
- Write-Host "[ERROR] Unsloth Studio requires an NVIDIA GPU." -ForegroundColor Red
- Write-Host " CPU-only machines are not supported." -ForegroundColor Red
+ Write-Host "[WARN] No NVIDIA GPU detected. Studio will run in chat-only (GGUF) mode." -ForegroundColor Yellow
+ Write-Host " Training and GPU inference require an NVIDIA GPU with drivers installed." -ForegroundColor Yellow
+ Write-Host " https://www.nvidia.com/Download/index.aspx" -ForegroundColor Yellow
Write-Host ""
- Write-Host " If you have an NVIDIA GPU, ensure the driver is installed:" -ForegroundColor Yellow
- Write-Host " https://www.nvidia.com/Download/index.aspx" -ForegroundColor Yellow
- exit 1
+} else {
+ Write-Host "[OK] NVIDIA GPU detected" -ForegroundColor Green
}
-Write-Host "[OK] NVIDIA GPU detected" -ForegroundColor Green
# ============================================
# 1a.5. Windows Long Paths (required for deep node_modules / Python paths)
@@ -341,6 +375,30 @@ if (-not $HasCmake) {
$HasCmake = $null -ne (Get-Command cmake -ErrorAction SilentlyContinue)
} catch { }
}
+ # winget may succeed but cmake isn't on PATH yet (MSI PATH changes need a
+ # new shell). Try the default install location as a fallback.
+ if (-not $HasCmake) {
+ $cmakeDefaults = @(
+ "$env:ProgramFiles\CMake\bin",
+ "${env:ProgramFiles(x86)}\CMake\bin",
+ "$env:LOCALAPPDATA\CMake\bin"
+ )
+ foreach ($d in $cmakeDefaults) {
+ if (Test-Path (Join-Path $d "cmake.exe")) {
+ $env:Path = "$d;$env:Path"
+ # Persist to user PATH so Refresh-Environment does not drop it later
+ $userPath = [Environment]::GetEnvironmentVariable('Path', 'User')
+ if (-not $userPath -or $userPath -notlike "*$d*") {
+ [Environment]::SetEnvironmentVariable('Path', "$d;$userPath", 'User')
+ }
+ $HasCmake = $null -ne (Get-Command cmake -ErrorAction SilentlyContinue)
+ if ($HasCmake) {
+ Write-Host " Found cmake at $d (added to PATH)" -ForegroundColor Gray
+ break
+ }
+ }
+ }
+ }
if ($HasCmake) {
Write-Host "[OK] CMake installed" -ForegroundColor Green
} else {
@@ -389,6 +447,7 @@ if ($vsResult) {
# ============================================
# 1e. CUDA Toolkit (nvcc for llama.cpp build + env vars)
# ============================================
+if ($HasNvidiaSmi) {
# IMPORTANT: The CUDA Toolkit version must be <= the max CUDA version the
# NVIDIA driver supports. nvidia-smi reports this as "CUDA Version: X.Y".
# If we install a toolkit newer than the driver supports, llama-server will
@@ -397,7 +456,7 @@ if ($vsResult) {
# -- Detect max CUDA version the driver supports --
$DriverMaxCuda = $null
try {
- $smiOut = nvidia-smi 2>&1 | Out-String
+ $smiOut = & $NvidiaSmiExe 2>&1 | Out-String
if ($smiOut -match "CUDA Version:\s+([\d]+)\.([\d]+)") {
$DriverMaxCuda = "$($Matches[1]).$($Matches[2])"
Write-Host " Driver supports up to CUDA $DriverMaxCuda" -ForegroundColor Gray
@@ -624,11 +683,24 @@ if ($VsInstallPath -and $CudaToolkitRoot) {
Copy-Item "$cudaExtras\*" $vsCustomizations -Force -ErrorAction Stop
Write-Host " [OK] CUDA VS integration files installed" -ForegroundColor Green
} catch {
- Write-Host " [WARN] Could not copy CUDA VS integration files (may need admin)" -ForegroundColor Yellow
- Write-Host " Manual fix: copy contents of" -ForegroundColor Yellow
- Write-Host " $cudaExtras" -ForegroundColor Cyan
- Write-Host " into:" -ForegroundColor Yellow
- Write-Host " $vsCustomizations" -ForegroundColor Cyan
+ # Direct copy failed (needs admin). Try elevated copy via Start-Process.
+ try {
+ $copyCmd = "Copy-Item '$cudaExtras\*' '$vsCustomizations' -Force"
+ Start-Process powershell -ArgumentList "-NoProfile -Command $copyCmd" -Verb RunAs -Wait -ErrorAction Stop
+ $hasTargetsRetry = Get-ChildItem $vsCustomizations -Filter "CUDA *.targets" -ErrorAction SilentlyContinue
+ if ($hasTargetsRetry) {
+ Write-Host " [OK] CUDA VS integration files installed (elevated)" -ForegroundColor Green
+ } else {
+ throw "Copy did not produce .targets files"
+ }
+ } catch {
+ Write-Host " [WARN] Could not copy CUDA VS integration files" -ForegroundColor Yellow
+ Write-Host " The llama.cpp build may fail with 'No CUDA toolset found'." -ForegroundColor Yellow
+ Write-Host " Manual fix: copy contents of" -ForegroundColor Yellow
+ Write-Host " $cudaExtras" -ForegroundColor Cyan
+ Write-Host " into:" -ForegroundColor Yellow
+ Write-Host " $vsCustomizations" -ForegroundColor Cyan
+ }
}
}
}
@@ -643,6 +715,9 @@ Write-Host " CudaToolkitDir = $CudaToolkitRoot\" -ForegroundColor Gray
if (-not $CudaArch) {
Write-Host " [WARN] Could not detect compute capability -- cmake will use defaults" -ForegroundColor Yellow
}
+} else {
+ Write-Host "[SKIP] CUDA Toolkit -- no NVIDIA GPU detected" -ForegroundColor Yellow
+}
# ============================================
# 1f. Node.js / npm (skip if pip-installed -- only needed for frontend build)
@@ -748,9 +823,40 @@ Write-Host ""
# ==========================================================================
# PHASE 2: Frontend build (skip if pip-installed -- already bundled)
# ==========================================================================
+$DistDir = Join-Path $FrontendDir "dist"
+# Skip build if dist/ exists and no tracked input is newer than dist/.
+# Checks src/, public/, package.json, config files -- not just src/.
+$NeedFrontendBuild = $true
if ($IsPipInstall) {
+ $NeedFrontendBuild = $false
Write-Host "[OK] Running from pip install - frontend already bundled, skipping build" -ForegroundColor Green
-} else {
+} elseif (Test-Path $DistDir) {
+ $DistTime = (Get-Item $DistDir).LastWriteTime
+ $NewerFile = $null
+ # Check src/ and public/ recursively (probe paths directly, not via -Include)
+ foreach ($subDir in @("src", "public")) {
+ $subPath = Join-Path $FrontendDir $subDir
+ if (Test-Path $subPath) {
+ $NewerFile = Get-ChildItem -Path $subPath -Recurse -File -ErrorAction SilentlyContinue |
+ Where-Object { $_.LastWriteTime -gt $DistTime } | Select-Object -First 1
+ if ($NewerFile) { break }
+ }
+ }
+ # Also check all top-level files (package.json, bun.lock, vite.config.ts, index.html, etc.)
+ if (-not $NewerFile) {
+ $NewerFile = Get-ChildItem -Path $FrontendDir -File -ErrorAction SilentlyContinue |
+ Where-Object { $_.LastWriteTime -gt $DistTime } |
+ Select-Object -First 1
+ }
+ if (-not $NewerFile) {
+ $NeedFrontendBuild = $false
+ Write-Host "[OK] Frontend already built and up to date -- skipping build" -ForegroundColor Green
+ } else {
+ Write-Host "[INFO] Frontend source changed since last build -- rebuilding..." -ForegroundColor Yellow
+ }
+}
+$NeedFrontendBuild = $true
+if ($NeedFrontendBuild -and -not $IsPipInstall) {
Write-Host ""
Write-Host "Building frontend..." -ForegroundColor Cyan
# npm writes warnings to stderr; lower ErrorActionPreference so PS doesn't
@@ -758,9 +864,6 @@ if ($IsPipInstall) {
$prevEAP_npm = $ErrorActionPreference
$ErrorActionPreference = "Continue"
Push-Location $FrontendDir
- # Remove stale node_modules and package-lock.json to avoid version conflicts
- if (Test-Path "node_modules") { Remove-Item -Recurse -Force "node_modules" }
- if (Test-Path "package-lock.json") { Remove-Item -Force "package-lock.json" }
npm install 2>&1 | Out-Null
if ($LASTEXITCODE -ne 0) {
Pop-Location
@@ -845,7 +948,35 @@ $ErrorActionPreference = "Continue"
$ActivateScript = Join-Path $VenvDir "Scripts\Activate.ps1"
. $ActivateScript
-pip install --upgrade pip 2>&1 | Out-Null
+
+# Try to use uv (much faster than pip), fall back to pip if unavailable
+$UseUv = $false
+if (Get-Command uv -ErrorAction SilentlyContinue) {
+ $UseUv = $true
+} else {
+ Write-Host " Installing uv package manager..." -ForegroundColor Cyan
+ try {
+ powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" 2>&1 | Out-Null
+ Refresh-Environment
+ # Re-activate venv since Refresh-Environment rebuilds PATH from
+ # registry and drops the venv's Scripts directory
+ . $ActivateScript
+ if (Get-Command uv -ErrorAction SilentlyContinue) { $UseUv = $true }
+ } catch { }
+}
+
+# Helper: install a package, preferring uv with pip fallback
+function Fast-Install {
+ param([Parameter(ValueFromRemainingArguments=$true)]$Args_)
+ if ($UseUv) {
+ $VenvPy = (Get-Command python).Source
+ $result = & uv pip install --python $VenvPy @Args_ 2>&1
+ if ($LASTEXITCODE -eq 0) { return }
+ }
+ & python -m pip install @Args_ 2>&1
+}
+
+Fast-Install --upgrade pip | Out-Null
# if (-not $IsPipInstall) {
# # Running from repo: copy requirements and do editable install
@@ -880,16 +1011,37 @@ $env:TORCHINDUCTOR_CACHE_DIR = $TorchCacheDir
[Environment]::SetEnvironmentVariable('TORCHINDUCTOR_CACHE_DIR', $TorchCacheDir, 'User')
Write-Host "[OK] TORCHINDUCTOR_CACHE_DIR set to $TorchCacheDir (avoids MAX_PATH issues)" -ForegroundColor Green
-$CuTag = Get-PytorchCudaTag
-Write-Host " Installing PyTorch with CUDA support ($CuTag)..." -ForegroundColor Cyan
-pip install torch torchvision torchaudio --index-url "https://download.pytorch.org/whl/$CuTag" 2>&1 | Out-Null
+if ($HasNvidiaSmi) {
+ $CuTag = Get-PytorchCudaTag
+ Write-Host " Installing PyTorch with CUDA support ($CuTag)..." -ForegroundColor Cyan
+ Write-Host " (This download is ~2.8 GB -- may take a few minutes)" -ForegroundColor Gray
+ $output = Fast-Install torch torchvision torchaudio --index-url "https://download.pytorch.org/whl/$CuTag" | Out-String
+ if ($LASTEXITCODE -ne 0) {
+ Write-Host "[FAILED] PyTorch CUDA install failed (exit code $LASTEXITCODE)" -ForegroundColor Red
+ Write-Host $output -ForegroundColor Red
+ exit 1
+ }
-# Install Triton for Windows (enables torch.compile β without it training can hang)
-Write-Host " Installing Triton for Windows..." -ForegroundColor Cyan
-pip install "triton-windows<3.7" 2>&1 | Out-Null
-Write-Host "[OK] Triton for Windows installed (enables torch.compile)" -ForegroundColor Green
+ # Install Triton for Windows (enables torch.compile -- without it training can hang)
+ Write-Host " Installing Triton for Windows..." -ForegroundColor Cyan
+ $output = Fast-Install "triton-windows<3.7" | Out-String
+ if ($LASTEXITCODE -ne 0) {
+ Write-Host "[WARN] Triton install failed -- torch.compile may not work" -ForegroundColor Yellow
+ Write-Host $output -ForegroundColor Yellow
+ } else {
+ Write-Host "[OK] Triton for Windows installed (enables torch.compile)" -ForegroundColor Green
+ }
+} else {
+ Write-Host " Installing PyTorch (CPU-only)..." -ForegroundColor Cyan
+ $output = Fast-Install torch torchvision torchaudio --index-url "https://download.pytorch.org/whl/cpu" | Out-String
+ if ($LASTEXITCODE -ne 0) {
+ Write-Host "[FAILED] PyTorch install failed (exit code $LASTEXITCODE)" -ForegroundColor Red
+ Write-Host $output -ForegroundColor Red
+ exit 1
+ }
+}
-# Ordered heavy dependency installation β shared cross-platform script
+# Ordered heavy dependency installation -- shared cross-platform script
Write-Host " Running ordered dependency installation..." -ForegroundColor Cyan
python "$PSScriptRoot\install_python_stack.py"
# Restore ErrorActionPreference after pip/python work
@@ -898,7 +1050,7 @@ $ErrorActionPreference = $prevEAP
# ββ Pre-install transformers 5.x into .venv_t5/ ββ
# Models like GLM-4.7-Flash need transformers>=5.3.0. Instead of pip-installing
# at runtime (slow, ~10-15s), we pre-install into a separate directory.
-# The training subprocess just prepends .venv_t5/ to sys.path β instant switch.
+# The training subprocess just prepends .venv_t5/ to sys.path -- instant switch.
Write-Host ""
Write-Host " Pre-installing transformers 5.x for newer model support..." -ForegroundColor Cyan
$VenvT5Dir = Join-Path $env:USERPROFILE ".unsloth\studio\.venv_t5"
@@ -906,17 +1058,20 @@ if (Test-Path $VenvT5Dir) { Remove-Item -Recurse -Force $VenvT5Dir }
New-Item -ItemType Directory -Path $VenvT5Dir -Force | Out-Null
$prevEAP_t5 = $ErrorActionPreference
$ErrorActionPreference = "Continue"
-pip install --target $VenvT5Dir --no-deps "transformers==5.3.0" 2>&1 | Out-Null
-if ($LASTEXITCODE -ne 0) {
- Write-Host "[FAIL] Could not install transformers 5.3.0 into .venv_t5/" -ForegroundColor Red
- $ErrorActionPreference = $prevEAP_t5
- exit 1
+foreach ($pkg in @("transformers==5.3.0", "huggingface_hub==1.7.1", "hf_xet==1.4.2")) {
+ $output = Fast-Install --target $VenvT5Dir --no-deps $pkg | Out-String
+ if ($LASTEXITCODE -ne 0) {
+ Write-Host "[FAIL] Could not install $pkg into .venv_t5/" -ForegroundColor Red
+ Write-Host $output -ForegroundColor Red
+ $ErrorActionPreference = $prevEAP_t5
+ exit 1
+ }
}
-pip install --target $VenvT5Dir --no-deps "huggingface_hub==1.3.0" 2>&1 | Out-Null
+# tiktoken is needed by Qwen-family tokenizers -- install with deps since
+# regex/requests may be missing on Windows
+$output = Fast-Install --target $VenvT5Dir tiktoken | Out-String
if ($LASTEXITCODE -ne 0) {
- Write-Host "[FAIL] Could not install huggingface_hub 1.3.0 into .venv_t5/" -ForegroundColor Red
- $ErrorActionPreference = $prevEAP_t5
- exit 1
+ Write-Host "[WARN] Could not install tiktoken into .venv_t5/ -- Qwen tokenizers may fail" -ForegroundColor Yellow
}
$ErrorActionPreference = $prevEAP_t5
Write-Host "[OK] Transformers 5.x pre-installed to .venv_t5/" -ForegroundColor Green
@@ -982,12 +1137,46 @@ $LlamaCppDir = Join-Path $UnslothHome "llama.cpp"
$BuildDir = Join-Path $LlamaCppDir "build"
$LlamaServerBin = Join-Path $BuildDir "bin\Release\llama-server.exe"
+$HasCmakeForBuild = $null -ne (Get-Command cmake -ErrorAction SilentlyContinue)
+
+# Check if existing llama-server matches current GPU mode. A CUDA-built binary
+# on a now-CPU-only machine (or vice versa) needs to be rebuilt.
+$NeedRebuild = $false
if (Test-Path $LlamaServerBin) {
+ $CmakeCacheFile = Join-Path $BuildDir "CMakeCache.txt"
+ if (Test-Path $CmakeCacheFile) {
+ $cachedCuda = Select-String -Path $CmakeCacheFile -Pattern 'GGML_CUDA:BOOL=ON' -Quiet
+ if ($HasNvidiaSmi -and -not $cachedCuda) {
+ Write-Host " Existing llama-server is CPU-only but GPU is available -- rebuilding" -ForegroundColor Yellow
+ $NeedRebuild = $true
+ } elseif (-not $HasNvidiaSmi -and $cachedCuda) {
+ Write-Host " Existing llama-server was built with CUDA but no GPU detected -- rebuilding" -ForegroundColor Yellow
+ $NeedRebuild = $true
+ }
+ }
+}
+
+if ((Test-Path $LlamaServerBin) -and -not $NeedRebuild) {
Write-Host ""
Write-Host "[OK] llama-server already exists at $LlamaServerBin" -ForegroundColor Green
+} elseif (-not $HasCmakeForBuild) {
+ Write-Host ""
+ if (-not $HasNvidiaSmi) {
+ # CPU-only machines depend entirely on llama-server for GGUF chat -- cmake is required
+ Write-Host "[ERROR] CMake is required to build llama-server for GGUF chat mode." -ForegroundColor Red
+ Write-Host " Install CMake from https://cmake.org/download/ and re-run setup." -ForegroundColor Yellow
+ exit 1
+ }
+ Write-Host "[SKIP] llama-server build -- cmake not available" -ForegroundColor Yellow
+ Write-Host " GGUF inference and export will not be available." -ForegroundColor Yellow
+ Write-Host " Install CMake from https://cmake.org/download/ and re-run setup." -ForegroundColor Yellow
} else {
Write-Host ""
- Write-Host "Building llama.cpp with CUDA support..." -ForegroundColor Cyan
+ if ($HasNvidiaSmi) {
+ Write-Host "Building llama.cpp with CUDA support..." -ForegroundColor Cyan
+ } else {
+ Write-Host "Building llama.cpp (CPU-only, no NVIDIA GPU detected)..." -ForegroundColor Cyan
+ }
Write-Host " This typically takes 5-10 minutes on first build." -ForegroundColor Gray
Write-Host ""
@@ -1007,17 +1196,19 @@ if (Test-Path $LlamaServerBin) {
# Re-sanitize CUDA_PATH_V* vars β Refresh-Environment (called during
# Node/Python installs above) may have repopulated conflicting versioned
# vars from the Machine registry.
- $cudaPathVars2 = @([Environment]::GetEnvironmentVariables('Process').Keys | Where-Object { $_ -match '^CUDA_PATH_V' })
- foreach ($v2 in $cudaPathVars2) {
- [Environment]::SetEnvironmentVariable($v2, $null, 'Process')
+ if ($HasNvidiaSmi -and $CudaToolkitRoot) {
+ $cudaPathVars2 = @([Environment]::GetEnvironmentVariables('Process').Keys | Where-Object { $_ -match '^CUDA_PATH_V' })
+ foreach ($v2 in $cudaPathVars2) {
+ [Environment]::SetEnvironmentVariable($v2, $null, 'Process')
+ }
+ $tkDirName2 = Split-Path $CudaToolkitRoot -Leaf
+ if ($tkDirName2 -match '^v(\d+)\.(\d+)') {
+ [Environment]::SetEnvironmentVariable("CUDA_PATH_V$($Matches[1])_$($Matches[2])", $CudaToolkitRoot, 'Process')
+ }
+ # Also re-assert CUDA_PATH and CudaToolkitDir in case they were overwritten
+ [Environment]::SetEnvironmentVariable('CUDA_PATH', $CudaToolkitRoot, 'Process')
+ [Environment]::SetEnvironmentVariable('CudaToolkitDir', "$CudaToolkitRoot\", 'Process')
}
- $tkDirName2 = Split-Path $CudaToolkitRoot -Leaf
- if ($tkDirName2 -match '^v(\d+)\.(\d+)') {
- [Environment]::SetEnvironmentVariable("CUDA_PATH_V$($Matches[1])_$($Matches[2])", $CudaToolkitRoot, 'Process')
- }
- # Also re-assert CUDA_PATH and CudaToolkitDir in case they were overwritten
- [Environment]::SetEnvironmentVariable('CUDA_PATH', $CudaToolkitRoot, 'Process')
- [Environment]::SetEnvironmentVariable('CudaToolkitDir', "$CudaToolkitRoot\", 'Process')
# -- Step A: Clone or pull llama.cpp --
@@ -1037,7 +1228,14 @@ if (Test-Path $LlamaServerBin) {
}
}
- # -- Step B: cmake configure (CUDA + Unsloth flags) --
+ # -- Step B: cmake configure --
+ # Clean stale CMake cache to prevent previous CUDA settings from leaking
+ # into a CPU-only rebuild (or vice versa).
+ $CmakeCacheFile = Join-Path $BuildDir "CMakeCache.txt"
+ if (Test-Path $CmakeCacheFile) {
+ Remove-Item -Recurse -Force $BuildDir
+ }
+
if ($BuildOk) {
Write-Host ""
Write-Host "--- cmake configure ---" -ForegroundColor Cyan
@@ -1066,37 +1264,45 @@ if (Test-Path $LlamaServerBin) {
$CmakeArgs += '-DLLAMA_CURL=OFF'
}
$CmakeArgs += '-DCMAKE_EXE_LINKER_FLAGS=/NODEFAULTLIB:LIBCMT'
- # CUDA flags (Unsloth-aligned)
- $CmakeArgs += '-DGGML_CUDA=ON'
- $CmakeArgs += "-DCUDAToolkit_ROOT=$CudaToolkitRoot"
- $CmakeArgs += "-DCUDA_TOOLKIT_ROOT_DIR=$CudaToolkitRoot"
- $CmakeArgs += "-DCMAKE_CUDA_COMPILER=$NvccPath"
- $CmakeArgs += '-DGGML_CUDA_FA_ALL_QUANTS=ON'
- $CmakeArgs += '-DGGML_CUDA_F16=OFF'
- $CmakeArgs += '-DGGML_CUDA_GRAPHS=OFF'
- $CmakeArgs += '-DGGML_CUDA_FORCE_CUBLAS=OFF'
- $CmakeArgs += '-DGGML_CUDA_PEER_MAX_BATCH_SIZE=8192'
- if ($CudaArch) {
- # Validate nvcc actually supports this architecture
- if (Test-NvccArchSupport -NvccExe $NvccPath -Arch $CudaArch) {
- $CmakeArgs += "-DCMAKE_CUDA_ARCHITECTURES=$CudaArch"
- } else {
- # GPU arch too new for this toolkit β fall back to highest supported.
- # PTX forward-compatibility will JIT-compile for the actual GPU at runtime.
- $maxArch = Get-NvccMaxArch -NvccExe $NvccPath
- if ($maxArch) {
- $CmakeArgs += "-DCMAKE_CUDA_ARCHITECTURES=$maxArch"
- Write-Host " [WARN] GPU is sm_$CudaArch but nvcc only supports up to sm_$maxArch" -ForegroundColor Yellow
- Write-Host " Building with sm_$maxArch (PTX will JIT for your GPU at runtime)" -ForegroundColor Yellow
+ # CUDA flags -- only if GPU available, otherwise explicitly disable
+ if ($HasNvidiaSmi -and $NvccPath) {
+ $CmakeArgs += '-DGGML_CUDA=ON'
+ $CmakeArgs += "-DCUDAToolkit_ROOT=$CudaToolkitRoot"
+ $CmakeArgs += "-DCUDA_TOOLKIT_ROOT_DIR=$CudaToolkitRoot"
+ $CmakeArgs += "-DCMAKE_CUDA_COMPILER=$NvccPath"
+ if ($CudaArch) {
+ # Validate nvcc actually supports this architecture
+ if (Test-NvccArchSupport -NvccExe $NvccPath -Arch $CudaArch) {
+ $CmakeArgs += "-DCMAKE_CUDA_ARCHITECTURES=$CudaArch"
+ } else {
+ # GPU arch too new for this toolkit -- fall back to highest supported.
+ # PTX forward-compatibility will JIT-compile for the actual GPU at runtime.
+ $maxArch = Get-NvccMaxArch -NvccExe $NvccPath
+ if ($maxArch) {
+ $CmakeArgs += "-DCMAKE_CUDA_ARCHITECTURES=$maxArch"
+ Write-Host " [WARN] GPU is sm_$CudaArch but nvcc only supports up to sm_$maxArch" -ForegroundColor Yellow
+ Write-Host " Building with sm_$maxArch (PTX will JIT for your GPU at runtime)" -ForegroundColor Yellow
+ }
+ # else: omit flag entirely, let cmake pick defaults
}
- # else: omit flag entirely, let cmake pick defaults
}
+ } else {
+ $CmakeArgs += '-DGGML_CUDA=OFF'
}
- cmake @CmakeArgs 2>&1 | Out-Null
+ $cmakeOutput = cmake @CmakeArgs 2>&1 | Out-String
if ($LASTEXITCODE -ne 0) {
$BuildOk = $false
$FailedStep = "cmake configure"
+ Write-Host $cmakeOutput -ForegroundColor Red
+ if ($cmakeOutput -match 'No CUDA toolset found|CUDA_TOOLKIT_ROOT_DIR|nvcc') {
+ Write-Host ""
+ Write-Host " Hint: CUDA VS integration may be missing. Try running as admin:" -ForegroundColor Yellow
+ Write-Host " Copy contents of:" -ForegroundColor Yellow
+ Write-Host " \extras\visual_studio_integration\MSBuildExtensions" -ForegroundColor Yellow
+ Write-Host " into:" -ForegroundColor Yellow
+ Write-Host " \MSBuild\Microsoft\VC\v170\BuildCustomizations" -ForegroundColor Yellow
+ }
}
}
@@ -1110,10 +1316,11 @@ if (Test-Path $LlamaServerBin) {
Write-Host " Parallel jobs: $NumCpu" -ForegroundColor Gray
Write-Host ""
- cmake --build $BuildDir --config Release --target llama-server -j $NumCpu 2>&1 | Out-Null
+ $output = cmake --build $BuildDir --config Release --target llama-server -j $NumCpu 2>&1 | Out-String
if ($LASTEXITCODE -ne 0) {
$BuildOk = $false
$FailedStep = "cmake build (llama-server)"
+ Write-Host $output -ForegroundColor Red
}
}
@@ -1121,9 +1328,10 @@ if (Test-Path $LlamaServerBin) {
if ($BuildOk) {
Write-Host ""
Write-Host "--- cmake build (llama-quantize) ---" -ForegroundColor Cyan
- cmake --build $BuildDir --config Release --target llama-quantize -j $NumCpu 2>&1 | Out-Null
+ $output = cmake --build $BuildDir --config Release --target llama-quantize -j $NumCpu 2>&1 | Out-String
if ($LASTEXITCODE -ne 0) {
Write-Host " [WARN] llama-quantize build failed (GGUF export may be unavailable)" -ForegroundColor Yellow
+ Write-Host $output -ForegroundColor Yellow
}
}
diff --git a/studio/setup.sh b/studio/setup.sh
index 4c8a6c7dde..02c49afc15 100755
--- a/studio/setup.sh
+++ b/studio/setup.sh
@@ -41,13 +41,27 @@ if [[ "$keynames" == *$'\nCOLAB_'* ]]; then
fi
# ββ Detect whether frontend needs building ββ
-# Only skip when BOTH conditions are true:
-# 1. We're inside site-packages (PyPI / pip install, not editable)
-# 2. dist/ already exists (pre-built in the wheel)
-# Otherwise always (re)build β handles upgrades, editable installs, and
-# pip-from-source where dist/ was never built.
-if [[ "$SCRIPT_DIR" == */site-packages/* ]] && [ -d "$SCRIPT_DIR/frontend/dist" ]; then
- echo "β
Frontend pre-built (PyPI) β skipping Node/npm check."
+# Skip if dist/ exists AND no tracked input is newer than dist/.
+# Checks top-level config/entry files and src/, public/ recursively.
+# This handles: PyPI installs (dist/ bundled), repeat runs (no changes),
+# and upgrades/pulls (source newer than dist/ triggers rebuild).
+_NEED_FRONTEND_BUILD=true
+if [ -d "$SCRIPT_DIR/frontend/dist" ]; then
+ # Check all top-level files (package.json, bun.lock, vite.config.ts, index.html, etc.)
+ _changed=$(find "$SCRIPT_DIR/frontend" -maxdepth 1 -type f \
+ -newer "$SCRIPT_DIR/frontend/dist" -print -quit 2>/dev/null)
+ # Check src/ and public/ recursively (|| true guards against set -e when dirs are missing)
+ if [ -z "$_changed" ]; then
+ _changed=$(find "$SCRIPT_DIR/frontend/src" "$SCRIPT_DIR/frontend/public" \
+ -type f -newer "$SCRIPT_DIR/frontend/dist" -print -quit 2>/dev/null) || true
+ fi
+ if [ -z "$_changed" ]; then
+ _NEED_FRONTEND_BUILD=false
+ fi
+fi
+_NEED_FRONTEND_BUILD=true
+if [ "$_NEED_FRONTEND_BUILD" = false ]; then
+ echo "β
Frontend already built and up to date -- skipping Node/npm check."
else
NEED_NODE=true
if command -v node &>/dev/null && command -v npm &>/dev/null; then
@@ -146,12 +160,17 @@ run_quiet "npm run build" npm run build
_restore_gitignores
trap - EXIT
-cd "$SCRIPT_DIR/backend/core/data_recipe/oxc-validator"
-run_quiet "npm install (oxc validator runtime)" npm install
cd "$SCRIPT_DIR"
echo "β
Frontend built to frontend/dist"
-fi # end frontend dist check
+fi # end frontend build check
+
+# ββ oxc-validator runtime (needs npm -- skip if not available) ββ
+if [ -d "$SCRIPT_DIR/backend/core/data_recipe/oxc-validator" ] && command -v npm &>/dev/null; then
+ cd "$SCRIPT_DIR/backend/core/data_recipe/oxc-validator"
+ run_quiet "npm install (oxc validator runtime)" npm install
+ cd "$SCRIPT_DIR"
+fi
# ββ 6. Python venv + deps ββ
@@ -223,50 +242,76 @@ install_python_stack() {
python "$SCRIPT_DIR/install_python_stack.py"
}
-if [ "$IS_COLAB" = true ]; then
- # Colab: install packages directly without venv
- install_python_stack
-else
- # Local: create venv under ~/.unsloth/studio/ (shared location, not in repo)
- STUDIO_HOME="$HOME/.unsloth/studio"
- VENV_DIR="$STUDIO_HOME/.venv"
- VENV_T5_DIR="$STUDIO_HOME/.venv_t5"
- mkdir -p "$STUDIO_HOME"
+# Create venv under ~/.unsloth/studio/ (shared location, not in repo).
+# All platforms (including Colab) use the same isolated venv so that
+# studio dependencies are never installed into the system Python.
+STUDIO_HOME="$HOME/.unsloth/studio"
+VENV_DIR="$STUDIO_HOME/.venv"
+VENV_T5_DIR="$STUDIO_HOME/.venv_t5"
+mkdir -p "$STUDIO_HOME"
- # Clean up legacy in-repo venvs if they exist
- [ -d "$REPO_ROOT/.venv" ] && rm -rf "$REPO_ROOT/.venv"
- [ -d "$REPO_ROOT/.venv_overlay" ] && rm -rf "$REPO_ROOT/.venv_overlay"
- [ -d "$REPO_ROOT/.venv_t5" ] && rm -rf "$REPO_ROOT/.venv_t5"
+# Clean up legacy in-repo venvs if they exist
+[ -d "$REPO_ROOT/.venv" ] && rm -rf "$REPO_ROOT/.venv"
+[ -d "$REPO_ROOT/.venv_overlay" ] && rm -rf "$REPO_ROOT/.venv_overlay"
+[ -d "$REPO_ROOT/.venv_t5" ] && rm -rf "$REPO_ROOT/.venv_t5"
- rm -rf "$VENV_DIR"
- rm -rf "$VENV_T5_DIR"
- "$BEST_PY" -m venv "$VENV_DIR"
+rm -rf "$VENV_DIR"
+rm -rf "$VENV_T5_DIR"
+# Try creating venv with pip; fall back to --without-pip + bootstrap
+# (some environments like Colab have broken ensurepip)
+if ! "$BEST_PY" -m venv "$VENV_DIR" 2>/dev/null; then
+ "$BEST_PY" -m venv --without-pip "$VENV_DIR"
source "$VENV_DIR/bin/activate"
- cd "$SCRIPT_DIR"
- install_python_stack
+ curl -sS https://bootstrap.pypa.io/get-pip.py | python > /dev/null
+else
+ source "$VENV_DIR/bin/activate"
+fi
- # ββ 6b. Pre-install transformers 5.x into .venv_t5/ ββ
- # Models like GLM-4.7-Flash need transformers>=5.3.0. Instead of pip-installing
- # at runtime (slow, ~10-15s), we pre-install into a separate directory.
- # The training subprocess just prepends .venv_t5/ to sys.path β instant switch.
- echo ""
- echo " Pre-installing transformers 5.x for newer model support..."
- mkdir -p "$VENV_T5_DIR"
- run_quiet "pip install transformers 5.x" pip install --target "$VENV_T5_DIR" --no-deps "transformers==5.3.0"
- run_quiet "pip install huggingface_hub for t5" pip install --target "$VENV_T5_DIR" --no-deps "huggingface_hub==1.3.0"
- echo "β
Transformers 5.x pre-installed to $VENV_T5_DIR/"
+# ββ Ensure uv is available (much faster than pip) ββ
+USE_UV=false
+if command -v uv &>/dev/null; then
+ USE_UV=true
+elif curl -LsSf https://astral.sh/uv/install.sh | sh > /dev/null 2>&1; then
+ export PATH="$HOME/.local/bin:$PATH"
+ command -v uv &>/dev/null && USE_UV=true
+fi
- # ββ 7. WSL: pre-install GGUF build dependencies ββ
- # On WSL, sudo requires a password and can't be entered during GGUF export
- # (runs in a non-interactive subprocess). Install build deps here instead.
- if grep -qi microsoft /proc/version 2>/dev/null; then
- echo ""
- echo "β οΈ WSL detected β installing build dependencies for GGUF export..."
- echo " You may be prompted for your password."
- sudo apt-get update -y
- sudo apt-get install -y build-essential cmake curl git libcurl4-openssl-dev
- echo "β
GGUF build dependencies installed"
+# Helper: install a package, preferring uv with pip fallback
+fast_install() {
+ if [ "$USE_UV" = true ]; then
+ uv pip install --python "$(command -v python)" "$@" && return 0
fi
+ python -m pip install "$@"
+}
+
+cd "$SCRIPT_DIR"
+install_python_stack
+
+# ββ 6b. Pre-install transformers 5.x into .venv_t5/ ββ
+# Models like GLM-4.7-Flash need transformers>=5.3.0. Instead of pip-installing
+# at runtime (slow, ~10-15s), we pre-install into a separate directory.
+# The training subprocess just prepends .venv_t5/ to sys.path -- instant switch.
+echo ""
+echo " Pre-installing transformers 5.x for newer model support..."
+mkdir -p "$VENV_T5_DIR"
+run_quiet "install transformers 5.x" fast_install --target "$VENV_T5_DIR" --no-deps "transformers==5.3.0"
+run_quiet "install huggingface_hub for t5" fast_install --target "$VENV_T5_DIR" --no-deps "huggingface_hub==1.7.1"
+run_quiet "install hf_xet for t5" fast_install --target "$VENV_T5_DIR" --no-deps "hf_xet==1.4.2"
+# tiktoken is needed by Qwen-family tokenizers. Install with deps since
+# regex/requests may be missing on Windows.
+run_quiet "install tiktoken for t5" fast_install --target "$VENV_T5_DIR" "tiktoken"
+echo "β
Transformers 5.x pre-installed to $VENV_T5_DIR/"
+
+# ββ 7. WSL: pre-install GGUF build dependencies ββ
+# On WSL, sudo requires a password and can't be entered during GGUF export
+# (runs in a non-interactive subprocess). Install build deps here instead.
+if grep -qi microsoft /proc/version 2>/dev/null; then
+ echo ""
+ echo "β οΈ WSL detected -- installing build dependencies for GGUF export..."
+ echo " You may be prompted for your password."
+ sudo apt-get update -y
+ sudo apt-get install -y build-essential cmake curl git libcurl4-openssl-dev
+ echo "β
GGUF build dependencies installed"
fi
# ββ 8. Build llama.cpp binaries for GGUF inference + export ββ
@@ -405,6 +450,9 @@ if [ "$IS_COLAB" = true ]; then
echo "β βββββββββββββββββββββββββββββββββββββββ£"
echo "β Unsloth Studio is ready to start β"
echo "β in your Colab notebook! β"
+ echo "β β"
+ echo "β from colab import start β"
+ echo "β start() β"
echo "ββββββββββββββββββββββββββββββββββββββββ"
else
echo "ββββββββββββββββββββββββββββββββββββββββ"
diff --git a/unsloth/models/_utils.py b/unsloth/models/_utils.py
index 116352c504..3333aa4003 100644
--- a/unsloth/models/_utils.py
+++ b/unsloth/models/_utils.py
@@ -12,7 +12,7 @@
# See the License for the specific language governing permissions and
# limitations under the License.
-__version__ = "2026.3.5"
+__version__ = "2026.3.6"
__all__ = [
"SUPPORTS_BFLOAT16",
@@ -242,8 +242,12 @@ def prefer_flex_attn_if_supported(model_class, config):
# decode q_len=1, causing ValueError. Needs transformers update.
# Gemma3N: timm vision wrappers (eg Gemma3nVisionConfig) do not
# support flex_attention.
+ # NemotronH: hybrid Mamba-2 + Transformer model that does not
+ # support flex_attention (raises NotImplementedError from transformers).
model_type = getattr(config, "model_type", "") if config else ""
- if model_type in ("gpt_oss", "mllama") or str(model_type).startswith("gemma3n"):
+ if model_type in ("gpt_oss", "mllama", "nemotron_h") or str(
+ model_type
+ ).startswith("gemma3n"):
return None
if config is not None:
setattr(config, "_attn_implementation", "flex_attention")
diff --git a/cli/__init__.py b/unsloth_cli/__init__.py
similarity index 68%
rename from cli/__init__.py
rename to unsloth_cli/__init__.py
index 434ee4d2ed..3b9043c5bf 100644
--- a/cli/__init__.py
+++ b/unsloth_cli/__init__.py
@@ -3,11 +3,11 @@
import typer
-from cli.commands.train import train
-from cli.commands.inference import inference
-from cli.commands.export import export, list_checkpoints
-from cli.commands.ui import ui
-from cli.commands.studio import studio_app
+from unsloth_cli.commands.train import train
+from unsloth_cli.commands.inference import inference
+from unsloth_cli.commands.export import export, list_checkpoints
+from unsloth_cli.commands.ui import ui
+from unsloth_cli.commands.studio import studio_app
app = typer.Typer(
help = "Command-line interface for Unsloth training, inference, and export.",
diff --git a/cli/commands/__init__.py b/unsloth_cli/commands/__init__.py
similarity index 100%
rename from cli/commands/__init__.py
rename to unsloth_cli/commands/__init__.py
diff --git a/cli/commands/export.py b/unsloth_cli/commands/export.py
similarity index 100%
rename from cli/commands/export.py
rename to unsloth_cli/commands/export.py
diff --git a/cli/commands/inference.py b/unsloth_cli/commands/inference.py
similarity index 100%
rename from cli/commands/inference.py
rename to unsloth_cli/commands/inference.py
diff --git a/cli/commands/studio.py b/unsloth_cli/commands/studio.py
similarity index 97%
rename from cli/commands/studio.py
rename to unsloth_cli/commands/studio.py
index da5198ad75..829f086b7d 100644
--- a/cli/commands/studio.py
+++ b/unsloth_cli/commands/studio.py
@@ -14,7 +14,7 @@ studio_app = typer.Typer(help = "Unsloth Studio commands.")
STUDIO_HOME = Path.home() / ".unsloth" / "studio"
-# __file__ is cli/commands/studio.py β two parents up is the package root
+# __file__ is unsloth_cli/commands/studio.py -- two parents up is the package root
# (either site-packages or the repo root for editable installs).
_PACKAGE_ROOT = Path(__file__).resolve().parent.parent.parent
@@ -33,7 +33,7 @@ def _find_run_py() -> Optional[Path]:
No CWD dependency β works from any directory.
Since studio/ is now a proper package (has __init__.py), it lives in
- site-packages after pip install, right next to cli/.
+ site-packages after pip install, right next to unsloth_cli/.
"""
# 1. Relative to __file__ (site-packages or editable repo root)
run_py = _PACKAGE_ROOT / "studio" / "backend" / "run.py"
diff --git a/cli/commands/train.py b/unsloth_cli/commands/train.py
similarity index 97%
rename from cli/commands/train.py
rename to unsloth_cli/commands/train.py
index 665956a80c..1157620092 100644
--- a/cli/commands/train.py
+++ b/unsloth_cli/commands/train.py
@@ -7,8 +7,8 @@ from typing import Optional
import typer
-from cli.config import Config, load_config
-from cli.options import add_options_from_config
+from unsloth_cli.config import Config, load_config
+from unsloth_cli.options import add_options_from_config
@add_options_from_config(Config)
diff --git a/cli/commands/ui.py b/unsloth_cli/commands/ui.py
similarity index 96%
rename from cli/commands/ui.py
rename to unsloth_cli/commands/ui.py
index 79a76e629b..eb6a8a69e8 100644
--- a/cli/commands/ui.py
+++ b/unsloth_cli/commands/ui.py
@@ -25,7 +25,11 @@ def ui(
),
):
"""Launch the Unsloth web UI backend server (alias for 'unsloth studio')."""
- from cli.commands.studio import _studio_venv_python, _find_run_py, STUDIO_HOME
+ from unsloth_cli.commands.studio import (
+ _studio_venv_python,
+ _find_run_py,
+ STUDIO_HOME,
+ )
# Re-execute in studio venv if available and not already inside it
studio_venv_dir = STUDIO_HOME / ".venv"
diff --git a/cli/config.py b/unsloth_cli/config.py
similarity index 100%
rename from cli/config.py
rename to unsloth_cli/config.py
diff --git a/cli/options.py b/unsloth_cli/options.py
similarity index 100%
rename from cli/options.py
rename to unsloth_cli/options.py
+### License
+Unsloth uses a dual-licensing model of Apache 2.0 and AGPL-3.0. The core Unsloth package remains licensed under **[Apache 2.0](https://github.com/unslothai/unsloth?tab=Apache-2.0-1-ov-file)**, while certain optional components, such as the Unsloth Studio UI are licensed under the open-source license **[AGPL-3.0](https://github.com/unslothai/unsloth?tab=AGPL-3.0-2-ov-file)**.
+
+This structure helps support ongoing Unsloth development while keeping the project open source and enabling the broader ecosystem to continue growing.
+
### Thank You to
- The [llama.cpp library](https://github.com/ggml-org/llama.cpp) that lets users run and save models with Unsloth
- The Hugging Face team and their libraries: [transformers](https://github.com/huggingface/transformers) and [TRL](https://github.com/huggingface/trl)
diff --git a/cli.py b/cli.py
index 0965b424e8..534babed2c 100644
--- a/cli.py
+++ b/cli.py
@@ -1,7 +1,7 @@
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
-from cli import app
+from unsloth_cli import app
if __name__ == "__main__":
app()
diff --git a/pyproject.toml b/pyproject.toml
index 5a75495c56..eaa7d84f71 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -55,7 +55,7 @@ dependencies = [
]
[project.scripts]
-unsloth = "cli:app"
+unsloth = "unsloth_cli:app"
[tool.setuptools.dynamic]
version = {attr = "unsloth.models._utils.__version__"}
@@ -737,6 +737,6 @@ cu130-ampere-torch2100 = [
]
[project.urls]
-homepage = "http://www.unsloth.ai"
-documentation = "https://github.com/unslothai/unsloth"
+homepage = "https://unsloth.ai"
+documentation = "https://unsloth.ai/docs"
repository = "https://github.com/unslothai/unsloth"
diff --git a/studio/Unsloth_Studio_Colab.ipynb b/studio/Unsloth_Studio_Colab.ipynb
index 0338fc3a47..c6a5378b85 100644
--- a/studio/Unsloth_Studio_Colab.ipynb
+++ b/studio/Unsloth_Studio_Colab.ipynb
@@ -15,11 +15,14 @@
"To install Unsloth Studio on your local device, follow [our guide](https://unsloth.ai/docs/new/unsloth-studio/install). Unsloth Studio is licensed [AGPL-3.0](https://github.com/unslothai/unsloth/blob/main/studio/LICENSE.AGPL-3.0).\n",
"\n",
"### Unsloth Studio\n",
- "\n",
- "Train and run open models with [**Unsloth Studio**](https://unsloth.ai/docs/new/unsloth-studio/start). Installation may take 10 mins.\n",
- "\n",
- "[Features](https://unsloth.ai/docs/new/unsloth-studio#features) β’ [Quickstart](https://unsloth.ai/docs/new/unsloth-studio/start) β’ [Data Recipes](https://unsloth.ai/docs/new/unsloth-studio/data-recipe) β’ [Studio Chat](https://unsloth.ai/docs/new/unsloth-studio/chat) β’ [Export](https://unsloth.ai/docs/new/unsloth-studio/export)"
- ]
+ "\n",
+ "Train and run open models with [**Unsloth Studio**](https://unsloth.ai/docs/new/unsloth-studio/start). Currently, installation may take 30+ mins so use a newer GPU.\n",
+ "\n",
+ "\n",
+ "We are actively working on making Unsloth Studio install on Colab T4 GPUs faster.\n",
+ "\n",
+ "[Features](https://unsloth.ai/docs/new/unsloth-studio#features) β’ [Quickstart](https://unsloth.ai/docs/new/unsloth-studio/start) β’ [Data Recipes](https://unsloth.ai/docs/new/unsloth-studio/data-recipe) β’ [Studio Chat](https://unsloth.ai/docs/new/unsloth-studio/chat) β’ [Export](https://unsloth.ai/docs/new/unsloth-studio/export)"
+ ]
},
{
"cell_type": "markdown",
diff --git a/studio/backend/colab.py b/studio/backend/colab.py
index 7162b6d4c2..f2f56b7f17 100644
--- a/studio/backend/colab.py
+++ b/studio/backend/colab.py
@@ -9,6 +9,32 @@ Uses Colab's built-in proxy - no external tunneling needed!
from pathlib import Path
import sys
+
+def _bootstrap_studio_venv() -> None:
+ """Expose the Studio venv's site-packages to the current interpreter.
+
+ On Colab, notebook cells run outside the venv subshell. Instead of
+ installing the full stack into system Python, we prepend the venv's
+ site-packages so that packages like structlog, fastapi, etc. are
+ importable from notebook cells and take priority over system copies.
+ """
+ venv_lib = Path.home() / ".unsloth" / "studio" / ".venv" / "lib"
+ if not venv_lib.exists():
+ import warnings
+
+ warnings.warn(
+ f"Studio venv not found at {venv_lib.parent} -- run 'unsloth studio setup' first",
+ stacklevel = 2,
+ )
+ return
+ for sp in venv_lib.glob("python*/site-packages"):
+ sp_str = str(sp)
+ if sp_str not in sys.path:
+ sys.path.insert(0, sp_str)
+
+
+_bootstrap_studio_venv()
+
# Add backend to path early so local modules like loggers can be imported
backend_path = str(Path(__file__).parent)
if backend_path not in sys.path:
diff --git a/studio/backend/core/__init__.py b/studio/backend/core/__init__.py
index 051f6615a7..d8d95e2f1a 100644
--- a/studio/backend/core/__init__.py
+++ b/studio/backend/core/__init__.py
@@ -10,6 +10,16 @@ like unsloth, transformers, or torch before the version activation
code has a chance to run.
"""
+import sys
+from pathlib import Path
+
+# Ensure the backend directory is on sys.path so that bare "from utils.*"
+# imports used throughout the backend work when core is imported as a package
+# (e.g. from the CLI: "from studio.backend.core import ModelConfig").
+_backend_dir = str(Path(__file__).resolve().parent.parent)
+if _backend_dir not in sys.path:
+ sys.path.insert(0, _backend_dir)
+
__all__ = [
# Inference
"InferenceBackend",
diff --git a/studio/backend/core/export/worker.py b/studio/backend/core/export/worker.py
index 4f74f662ee..6af6ff1193 100644
--- a/studio/backend/core/export/worker.py
+++ b/studio/backend/core/export/worker.py
@@ -40,59 +40,25 @@ def _activate_transformers_version(model_name: str) -> None:
if backend_path not in sys.path:
sys.path.insert(0, backend_path)
- from utils.transformers_version import needs_transformers_5, _resolve_base_model
+ from utils.transformers_version import (
+ needs_transformers_5,
+ _resolve_base_model,
+ _ensure_venv_t5_exists,
+ _VENV_T5_DIR,
+ )
resolved = _resolve_base_model(model_name)
if needs_transformers_5(resolved):
- venv_t5 = os.path.join(
- os.path.expanduser("~"), ".unsloth", "studio", ".venv_t5"
- )
- if os.path.isdir(venv_t5):
- sys.path.insert(0, venv_t5)
- logger.info("Activated transformers 5.x from %s", venv_t5)
- else:
- # Fallback: pip install at runtime (slower, ~10-15s)
- logger.warning(".venv_t5 not found at %s β installing at runtime", venv_t5)
- import subprocess as sp
-
- os.makedirs(venv_t5, exist_ok = True)
- r1 = sp.run(
- [
- sys.executable,
- "-m",
- "pip",
- "install",
- "--target",
- venv_t5,
- "--no-deps",
- "transformers==5.3.0",
- ],
- stdout = sp.PIPE,
- stderr = sp.STDOUT,
+ if not _ensure_venv_t5_exists():
+ raise RuntimeError(
+ f"Cannot activate transformers 5.x: .venv_t5 missing at {_VENV_T5_DIR}"
)
- r2 = sp.run(
- [
- sys.executable,
- "-m",
- "pip",
- "install",
- "--target",
- venv_t5,
- "--no-deps",
- "huggingface_hub==1.3.0",
- ],
- stdout = sp.PIPE,
- stderr = sp.STDOUT,
- )
- if r1.returncode != 0 or r2.returncode != 0:
- raise RuntimeError(
- f"Failed to install transformers 5.x into {venv_t5}. "
- f"pip returncode: transformers={r1.returncode}, huggingface_hub={r2.returncode}"
- )
- sys.path.insert(0, venv_t5)
+ if _VENV_T5_DIR not in sys.path:
+ sys.path.insert(0, _VENV_T5_DIR)
+ logger.info("Activated transformers 5.x from %s", _VENV_T5_DIR)
# Propagate to child subprocesses (e.g. GGUF converter)
_pp = os.environ.get("PYTHONPATH", "")
- os.environ["PYTHONPATH"] = venv_t5 + (os.pathsep + _pp if _pp else "")
+ os.environ["PYTHONPATH"] = _VENV_T5_DIR + (os.pathsep + _pp if _pp else "")
else:
logger.info("Using default transformers (4.57.x) for %s", model_name)
diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.py
index 64a7324adf..8054bd2a19 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -1173,50 +1173,113 @@ class LlamaCppBackend:
Handles formats like: