Skip to content

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

Studio: show the AMD NPU by default again, with a clearer setup notice (#14524)

Daniel Han3f22b3d2ef6e
diff --git a/studio/backend/core/inference/npu_backend.py b/studio/backend/core/inference/npu_backend.py
index 5af1585f5d2..ef99853980f 100644
--- a/studio/backend/core/inference/npu_backend.py
+++ b/studio/backend/core/inference/npu_backend.py
@@ -438,8 +438,8 @@ class LemonadeNpuBackend:
raise NpuError("No AMD Ryzen AI NPU was found on this machine.")
if hardware.get("family") == "XDNA2" and hardware.get("enabled") is False:
raise NpuError(
- "The AMD NPU is off by default. Start Unsloth Studio with "
- "UNSLOTH_STUDIO_ENABLE_NPU=1 to use it."
+ "The AMD NPU is turned off by UNSLOTH_STUDIO_ENABLE_NPU. Unset it or set it "
+ "to 1, then restart Unsloth Studio to use the NPU."
)
if not hardware.get("supported"):
raise NpuError(
diff --git a/studio/backend/tests/test_npu_backend.py b/studio/backend/tests/test_npu_backend.py
index 1b5900e1123..5b682233cb8 100644
--- a/studio/backend/tests/test_npu_backend.py
+++ b/studio/backend/tests/test_npu_backend.py
@@ -157,7 +157,7 @@ def test_an_npu_left_off_is_refused_with_the_flag_named(tmp_path, monkeypatch, c
lambda: {"present": True, "enabled": False, "supported": False, "family": "XDNA2"},
)
backend = nb.LemonadeNpuBackend(root = tmp_path / "lemonade")
- with pytest.raises(nb.NpuError, match = "UNSLOTH_STUDIO_ENABLE_NPU=1"):
+ with pytest.raises(nb.NpuError, match = "UNSLOTH_STUDIO_ENABLE_NPU. Unset it"):
getattr(backend, call)()
assert installer.installs == 0
assert backend.status()["supported"] is False
diff --git a/studio/backend/tests/test_npu_detect.py b/studio/backend/tests/test_npu_detect.py
index 503b3a6fbeb..0dbe717cad8 100644
--- a/studio/backend/tests/test_npu_detect.py
+++ b/studio/backend/tests/test_npu_detect.py
@@ -84,8 +84,11 @@ def test_only_xdna2_is_supported(tmp_path, monkeypatch, device, supported):
assert info["supported"] is supported
[email protected]("value", [None, "", "0", "false"])
-def test_an_xdna2_npu_is_off_without_the_flag(tmp_path, monkeypatch, value):
+ "value, enabled",
+ [(None, True), ("", True), ("1", True), ("0", False), ("false", False), (" Off ", False)],
+)
+def test_an_xdna2_npu_is_on_unless_the_flag_turns_it_off(tmp_path, monkeypatch, value, enabled):
_device(tmp_path, "0000:c4:00.1", "1022", "17f0", driver = "amdxdna")
probe = npu._linux_probe
monkeypatch.setattr(npu.sys, "platform", "linux")
@@ -98,7 +101,7 @@ def test_an_xdna2_npu_is_off_without_the_flag(tmp_path, monkeypatch, value):
monkeypatch.setenv(npu.ENABLE_ENV, value)
info = npu.detect_amd_npu()
assert info["present"] is True and info["family"] == "XDNA2"
- assert info["enabled"] is False and info["supported"] is False
+ assert info["enabled"] is enabled and info["supported"] is enabled
def test_detection_never_raises(monkeypatch):
@@ -111,6 +114,6 @@ def test_detection_never_raises(monkeypatch):
assert npu.detect_amd_npu() == {
"present": False,
"error": "sysfs",
- "enabled": False,
+ "enabled": True,
"supported": False,
}
diff --git a/studio/backend/utils/hardware/npu.py b/studio/backend/utils/hardware/npu.py
index b2d735e4c6d..ea5ea4aa4d7 100644
--- a/studio/backend/utils/hardware/npu.py
+++ b/studio/backend/utils/hardware/npu.py
@@ -3,7 +3,7 @@
"""Detect AMD NPUs without starting a runtime.
-XDNA 2 (1022:17f0) is supported, and only with ``UNSLOTH_STUDIO_ENABLE_NPU=1``; XDNA 1
+XDNA 2 (1022:17f0) is supported unless ``UNSLOTH_STUDIO_ENABLE_NPU=0`` hides it; XDNA 1
(1022:1502) is not. Runtime readiness is checked separately by ``flm validate``.
"""
@@ -19,12 +19,12 @@ _XDNA2_DEVICE = "17f0"
_XDNA1_DEVICE = "1502"
_PCI_ROOT = Path("/sys/bus/pci/devices")
_MODULE_ROOT = Path("/sys/module")
-# Off by default: the NPU section, NPU loads and the CLI's NPU ids all wait on this.
+# On unless set to a false value: the NPU section, NPU loads and the CLI's NPU ids all wait on this.
ENABLE_ENV = "UNSLOTH_STUDIO_ENABLE_NPU"
def npu_enabled() -> bool:
- return os.environ.get(ENABLE_ENV, "").strip().lower() in ("1", "true", "yes", "on")
+ return os.environ.get(ENABLE_ENV, "").strip().lower() not in ("0", "false", "no", "off")
def _read(path: Path) -> Optional[str]:
diff --git a/studio/frontend/scripts/check-bundle-budget.ts b/studio/frontend/scripts/check-bundle-budget.ts
index f35a91de85a..9a311e09a7e 100644
--- a/studio/frontend/scripts/check-bundle-budget.ts
+++ b/studio/frontend/scripts/check-bundle-budget.ts
@@ -348,8 +348,10 @@ export const BUDGET = {
// REAP on the Export page (#14130) passes its options through the eager export runtime store (the card is
// in the lazy export page): +371 B raw / +119 B transfer (6,878,631 -> 6,879,002 B raw, 2,071,507 ->
// 2,071,626 B transfer against 4df9ce74f, one machine and build, Node 24, 97 chunks). Raised by that.
- transferBytes: 2_071_693,
- rawBytes: 6_879_150,
+ // The NPU setup card (#14524): +439 B raw / +122 B transfer against fc91656ff (Node 24, 97 chunks), where main
+ // was already 1 B transfer over; transfer set to the measured build, raw raised by the growth.
+ transferBytes: 2_071_816,
+ rawBytes: 6_879_589,
};
// 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/features/npu/npu-setup-notice.tsx b/studio/frontend/src/features/npu/npu-setup-notice.tsx
index 2d23e13d927..fa003f83355 100644
--- a/studio/frontend/src/features/npu/npu-setup-notice.tsx
+++ b/studio/frontend/src/features/npu/npu-setup-notice.tsx
@@ -8,14 +8,21 @@ import { HugeiconsIcon } from "@hugeicons/react";
import type { NpuCatalog } from "./use-npu-catalog";
export function NpuSetupNotice({ catalog }: { catalog: NpuCatalog }) {
- const { status, ready, models, listError, enabling, enable } = catalog;
+ const { status, ready, models, listError } = catalog;
const problems = status.validation?.problems ?? [];
+ const setUp = ready && status.runtime_installed;
return (
- <div className="flex flex-col gap-2 px-2.5 pb-2 text-xs">
- <p className="text-muted-foreground">
- {status.hardware.name ?? "AMD NPU"} found. These models run on the NPU,
- separately from the GPU models listed below.
- </p>
+ <div
+ data-testid="npu-setup-notice"
+ className="flex flex-col gap-2 px-2.5 pb-2 text-xs"
+ >
+ {setUp ? (
+ <p className="text-muted-foreground">
+ These models run on the AMD NPU, not on the GPU.
+ </p>
+ ) : (
+ <NpuEnableCard catalog={catalog} />
+ )}
{status.error || problems.length > 0 ? (
<div className="flex gap-2 rounded-lg bg-destructive/10 p-2.5 text-destructive">
<HugeiconsIcon
@@ -37,26 +44,10 @@ export function NpuSetupNotice({ catalog }: { catalog: NpuCatalog }) {
</div>
</div>
) : null}
- {!ready || !status.runtime_installed ? (
- <div className="flex items-center justify-between gap-3 rounded-lg bg-muted/50 p-3">
- <span className="text-muted-foreground">
- Enabling downloads Lemonade (about 7 MB) and FastFlowLM (about 40
- MB), then checks the NPU driver.
- </span>
- <Button size="sm" onClick={() => void enable()} disabled={enabling}>
- {enabling ? <Spinner className="size-3.5" /> : null}
- {status.state === "failed"
- ? "Try again"
- : status.runtime_installed
- ? "Start NPU runtime"
- : "Enable NPU"}
- </Button>
- </div>
- ) : null}
{listError && listError !== status.error ? (
<p className="text-destructive">{listError}</p>
) : null}
- {ready && status.runtime_installed && !models && !listError ? (
+ {setUp && !models && !listError ? (
<div className="flex justify-center py-2">
<Spinner className="size-3.5 text-muted-foreground" />
</div>
@@ -64,3 +55,35 @@ export function NpuSetupNotice({ catalog }: { catalog: NpuCatalog }) {
</div>
);
}
+
+function NpuEnableCard({ catalog }: { catalog: NpuCatalog }) {
+ const { status, enabling, enable } = catalog;
+ const action =
+ status.state === "failed"
+ ? "Try again"
+ : status.runtime_installed
+ ? "Start NPU runtime"
+ : "Enable NPU";
+ return (
+ <div className="flex flex-col gap-2 rounded-lg bg-muted/50 p-3">
+ <p className="font-medium text-foreground">
+ This PC has an AMD Ryzen AI NPU
+ </p>
+ <p className="text-muted-foreground">
+ The NPU runs its own builds of models such as Qwen and Gemma, alongside
+ your GPU models rather than instead of them. Enable it to see them.
+ </p>
+ <div className="flex items-center justify-between gap-3">
+ <span className="text-muted-foreground">
+ {status.runtime_installed
+ ? "Finishes setup and checks the NPU driver."
+ : "One-time setup: downloads about 47 MB and checks the NPU driver."}
+ </span>
+ <Button size="sm" onClick={() => void enable()} disabled={enabling}>
+ {enabling ? <Spinner className="size-3.5" /> : null}
+ {action}
+ </Button>
+ </div>
+ </div>
+ );
+}
diff --git a/unsloth_cli/_npu.py b/unsloth_cli/_npu.py
index 829052bba9a..0e75ae9f4ad 100644
--- a/unsloth_cli/_npu.py
+++ b/unsloth_cli/_npu.py
@@ -86,8 +86,8 @@ def _prepare_npu_model(
reason = "no AMD Ryzen AI NPU was found on this machine"
elif hardware.get("family") == "XDNA2" and hardware.get("enabled") is False:
reason = (
- "the NPU is off by default. Start Unsloth Studio with "
- "UNSLOTH_STUDIO_ENABLE_NPU=1 to use it"
+ "the NPU is turned off in this Unsloth Studio. Restart it with "
+ "UNSLOTH_STUDIO_ENABLE_NPU=1 to use the NPU"
)
else:
reason = (