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.

fix(amd): turn on PyTorch's fast ROCm attention kernels on import unsloth, and drop the installers' host-wide export (#8821)

Leo Borcherding164d154dd281
diff --git a/install.sh b/install.sh
index d4d586efb41..bf50697d862 100755
--- a/install.sh
+++ b/install.sh
@@ -4287,7 +4287,6 @@ _persist_rocm_wsl_dropin() {
[ -e /opt/rocm/lib/librocdxg.so ] || [ -e /opt/rocm/lib64/librocdxg.so ] || return 0
_rw_rocm=/opt/rocm
export HSA_ENABLE_DXG_DETECTION=1
- export TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL=1
case ":${PATH}:" in
*":${_rw_rocm}/bin:"*) ;;
*) export PATH="${_rw_rocm}/bin:${PATH}" ;;
@@ -4297,7 +4296,6 @@ _persist_rocm_wsl_dropin() {
_rw_dropin="$(
printf '# >>> Unsloth ROCm-on-WSL (gfx1151) >>>\n'
printf 'export HSA_ENABLE_DXG_DETECTION=1\n'
- printf 'export TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL=1\n'
printf 'export PATH="%s/bin:${PATH}"\n' "${_rw_rocm}"
printf 'export LD_LIBRARY_PATH="%s/lib:${LD_LIBRARY_PATH:-}"\n' "${_rw_rocm}"
printf '# <<< Unsloth ROCm-on-WSL (gfx1151) <<<\n'
@@ -4348,7 +4346,7 @@ _maybe_bootstrap_rocm_wsl() {
substep "One-time, uses sudo and a large download. (skip: re-run with UNSLOTH_SKIP_ROCM_WSL_SETUP=1)"
# Locate the helper: prefer the copy shipped beside install.sh, else fetch it. The local copy counts only for a --local checkout run, since this executes with no prompt and _REPO_ROOT may otherwise be the caller's cwd. PINNED, never a branch: this runs unattended and installs with sudo, so a moving ref would turn any rewrite of that branch into root code on every affected WSL box. Bump it whenever the helper changes; lagging only means an older helper, and the gate below rejects one too old to be safe.
- _ROCM_WSL_HELPER_REF="d3367edd9a1de7a0ac15aa899bd9cb97173679dc"
+ _ROCM_WSL_HELPER_REF="b1d829182f8c490a326cf7690f156d2de06381f2"
# librocdxg pin (v1.2.2), forwarded to the helper. The ref IS the commit, so an older helper that ignores the SHA still resolves this exact revision: its `--branch <sha>` attempt fails and the full clone plus checkout land on it. Kept equal to the helper's defaults; a test enforces that. A user-set ref wins and, with no SHA of its own, turns the helper's check off rather than failing against our pin.
_rw_dxg_ref="${UNSLOTH_LIBROCDXG_REF:-}"
_rw_dxg_sha="${UNSLOTH_LIBROCDXG_SHA:-}"
diff --git a/scripts/install_rocm_wsl_strixhalo.sh b/scripts/install_rocm_wsl_strixhalo.sh
index 63d6e06fc60..b860b7d570c 100644
--- a/scripts/install_rocm_wsl_strixhalo.sh
+++ b/scripts/install_rocm_wsl_strixhalo.sh
@@ -257,7 +257,6 @@ _envfile="/etc/profile.d/unsloth-rocm-wsl.sh"
$SUDO tee "$_envfile" >/dev/null <<EOF
# >>> Unsloth ROCm-on-WSL >>>
export HSA_ENABLE_DXG_DETECTION=1
-export TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL=1
export PATH="${ROCM_DIR}/bin:\${PATH}"
export LD_LIBRARY_PATH="${ROCM_DIR}/lib:\${LD_LIBRARY_PATH:-}"
# <<< Unsloth ROCm-on-WSL <<<
diff --git a/studio/backend/main.py b/studio/backend/main.py
index 2861de646ca..859809780b6 100644
--- a/studio/backend/main.py
+++ b/studio/backend/main.py
@@ -18,6 +18,10 @@ os.environ["PYTHONWARNINGS"] = "ignore"
# from nvidia-smi can resolve to a different card. setdefault so an override wins; see utils/hardware/hardware.py.
os.environ.setdefault("CUDA_DEVICE_ORDER", "PCI_BUS_ID")
+# Same ROCm AOTriton opt-in as unsloth/__init__.py, for a backend that defers importing torch;
+# spawned workers inherit it. `setdefault` preserves an explicit override, including "0".
+os.environ.setdefault("TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL", "1")
+
# Windows terminals default to the active system code page. Reconfigure stdout/stderr
# before the startup banner so non-ASCII output cannot crash the backend process.
if sys.platform == "win32":
diff --git a/tests/python/test_rocm_aotriton_gate.py b/tests/python/test_rocm_aotriton_gate.py
new file mode 100644
index 00000000000..fcb2dcead62
--- /dev/null
+++ b/tests/python/test_rocm_aotriton_gate.py
@@ -0,0 +1,191 @@
+"""Unsloth and Studio both open the ROCm AOTriton SDPA gate, whatever loaded first.
+
+Torch fixes TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL at the first ROCm SDPA probe, not at
+extension load (function-local `static const bool` in the `check_*_hardware_support` helpers
+of `aten/src/ATen/native/transformers/cuda/sdp_utils.cpp`, unchanged 2.8 through main), so
+`import torch` first, the order `studio/backend/core/training/trainer.py` uses, is still in
+time; skipping the write leaves the quadratic MATH path #8819 measured.
+
+The write is a bare `os.environ.setdefault` in both files, asserted below: any version or
+architecture policy would have to import torch and would shadow AOTriton's experimental
+matrix, which ships inside the wheel and moves between releases and builds.
+"""
+
+import ast
+import functools
+import os
+import pathlib
+import subprocess
+import sys
+import types
+
+import pytest
+
+_ROOT = pathlib.Path(__file__).resolve().parents[2]
+_INIT = _ROOT / "unsloth" / "__init__.py"
+_STUDIO_MAIN = _ROOT / "studio" / "backend" / "main.py"
+_STUDIO_RUN = _ROOT / "studio" / "backend" / "run.py"
+_GATE = "TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL"
+
+
+def _source(path):
+ return path.read_text(encoding = "utf-8")
+
+
+def _gate_statement(path):
+ """The top-level statement that opens the gate, with any block it sits in."""
+ for node in ast.parse(_source(path)).body:
+ if _GATE in ast.unparse(node):
+ return node
+ raise AssertionError(f"no top-level statement in {path} sets {_GATE}")
+
+
+def _open_gate(path, modules, environ):
+ """Exec the statement against a synthetic `sys.modules` / environ; running it rather than
+ grepping the source keeps a re-added guard visible."""
+ scope = {
+ "os": types.SimpleNamespace(environ = environ),
+ "sys": types.SimpleNamespace(modules = modules),
+ }
+ exec(ast.unparse(_gate_statement(path)), scope)
+
+
+def _first_torch_import(path):
+ """Where the file first imports torch, at any nesting depth."""
+ return min(
+ (
+ node.lineno
+ for node in ast.walk(ast.parse(_source(path)))
+ if (
+ isinstance(node, ast.Import)
+ and any(alias.name.split(".")[0] == "torch" for alias in node.names)
+ )
+ or (isinstance(node, ast.ImportFrom) and (node.module or "").split(".")[0] == "torch")
+ ),
+ default = 10**9,
+ )
+
+
+_GATE_FILES = pytest.mark.parametrize("path", [_INIT, _STUDIO_MAIN], ids = ["unsloth", "studio"])
+
+
+@_GATE_FILES
+def test_an_unset_gate_is_opened(path):
+ environ = {}
+ _open_gate(path, {}, environ)
+ assert environ.get(_GATE) == "1"
+
+
+@_GATE_FILES
+def test_an_already_imported_torch_does_not_skip_the_write(path):
+ """The regression a `"torch" not in sys.modules` guard reintroduces: torch has not read
+ the variable yet, so the write still decides the gate."""
+ environ = {}
+ _open_gate(path, {"torch": types.ModuleType("torch")}, environ)
+ assert environ.get(_GATE) == "1"
+
+
+@_GATE_FILES
[email protected]("value", ["0", "1"])
+def test_an_explicit_value_is_never_overwritten(path, value):
+ """`c10::utils::check_env` reads "0" as the opt-out, so it must survive both orderings."""
+ for modules in ({}, {"torch": types.ModuleType("torch")}):
+ environ = {_GATE: value}
+ _open_gate(path, modules, environ)
+ assert environ[_GATE] == value
+
+
+@_GATE_FILES
+def test_the_gate_is_a_bare_setdefault_that_cannot_reach_torch(path):
+ """Exactly `os.environ.setdefault(<name>, "1")` with two literals, so nothing it runs can
+ import torch or grow a policy that has to track AOTriton's experimental set."""
+ node = _gate_statement(path)
+ assert isinstance(node, ast.Expr), ast.unparse(node)
+ call = node.value
+ assert isinstance(call, ast.Call), ast.unparse(node)
+ assert ast.unparse(call.func) == "os.environ.setdefault"
+ assert not call.keywords
+ assert [getattr(arg, "value", None) for arg in call.args] == [_GATE, "1"]
+
+
+@_GATE_FILES
+def test_the_gate_precedes_the_files_own_torch_import(path):
+ """Only read at the first SDPA probe, but staying above every torch import keeps it so."""
+ assert _gate_statement(path).lineno < _first_torch_import(path)
+
+
+def test_studio_opens_the_gate_before_route_and_hardware_imports():
+ source = _source(_STUDIO_MAIN)
+ gate = _gate_statement(_STUDIO_MAIN).lineno
+ for marker in ("from routes import (", "from utils.hardware import ("):
+ assert source.index(marker) > 0, marker
+ assert source[: source.index(marker)].count("\n") + 1 > gate, marker
+
+
+def test_all_studio_launches_converge_on_the_main_gate():
+ """`run.py` execs the app, so it cannot disagree with a direct `uvicorn main:app`."""
+ source = _source(_STUDIO_RUN)
+ assert _GATE not in source
+ assert "from main import app" in source
+
+
+def test_installers_never_persist_the_gate():
+ """The AOTriton opt-in belongs to Unsloth processes, not system or user config."""
+ for name in (
+ "install.sh",
+ "install.ps1",
+ "scripts/install_rocm_wsl_strixhalo.sh",
+ "scripts/uninstall.sh",
+ "scripts/uninstall.ps1",
+ ):
+ assert _GATE not in _source(_ROOT / name), name
+
+
+def _run(code, **env):
+ """Run `code` in a fresh interpreter, so no module state leaks between cases."""
+ path = [str(_ROOT)]
+ if os.environ.get("PYTHONPATH"):
+ path.append(os.environ["PYTHONPATH"])
+ # Importing Unsloth sets the gate; each case supplies its own starting value.
+ clean = {k: v for k, v in os.environ.items() if k != _GATE}
+ return subprocess.run(
+ [sys.executable, "-c", code],
+ capture_output = True,
+ text = True,
+ env = dict(clean, PYTHONPATH = os.pathsep.join(path), **env),
+ timeout = 900,
+ )
+
+
+def _unsloth_is_importable():
+ return _run("import unsloth").returncode == 0
+
+
+def _needs_unsloth():
+ if not _unsloth_is_importable():
+ pytest.skip("unsloth is not importable in this environment")
+
+
+_REPORT = "import os, unsloth\nprint('GATE', os.environ.get({name!r}))".format(name = _GATE)
+
+
+ "prologue",
+ ["", "import torch\n"],
+ ids = ["unsloth_first", "torch_first"],
+)
+def test_importing_unsloth_opens_the_gate(prologue):
+ """The end-to-end shape of #8819, both ways round."""
+ _needs_unsloth()
+ out = _run(prologue + _REPORT)
+ assert out.returncode == 0, out.stderr
+ assert "GATE 1" in out.stdout, out.stdout
+
+
+def test_an_explicit_opt_out_survives_the_import():
+ _needs_unsloth()
+ out = _run(_REPORT, **{_GATE: "0"})
+ assert out.returncode == 0, out.stderr
+ assert "GATE 0" in out.stdout, out.stdout
diff --git a/unsloth/__init__.py b/unsloth/__init__.py
index 6d983cf32e8..36c28e1615b 100644
--- a/unsloth/__init__.py
+++ b/unsloth/__init__.py
@@ -13,6 +13,11 @@ import os, importlib.util, platform, sys
os.environ["UNSLOTH_IS_PRESENT"] = "1"
+# Opt into ROCm AOTriton kernels PyTorch still gates as experimental; it keeps its own hardware
+# checks and reads this lazily at the SDPA probe, so no torch import here. `setdefault` preserves
+# an explicit override, including "0".
+os.environ.setdefault("TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL", "1")
+
# Before transformers, which reads sentencepiece availability during its own import. On Windows
# the extension is never imported at all: a code integrity policy can refuse it by reputation,
# and any probe to find out whether this machine will is itself the refusal the user sees. See