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: fix image and video loads on torchao 0.14 (FqnToConfig import error with diffusers 0.41) (#13308)

Daniel Hanec65aaf52e73
diff --git a/studio/backend/core/_torchao_stub.py b/studio/backend/core/_torchao_stub.py
index add31323a6d..47067d8cd35 100644
--- a/studio/backend/core/_torchao_stub.py
+++ b/studio/backend/core/_torchao_stub.py
@@ -228,6 +228,50 @@ def install_torchao_windows_rocm_stub() -> None:
sys.modules[_tao_name] = _make_mod_stub(_tao_name)
+_FQN_TO_CONFIG_SINCE = (0, 15)
+
+
+def _alias_fqn_to_config_now() -> None:
+ if is_stubbed("torchao"):
+ return
+ try:
+ version = importlib.metadata.version("torchao")
+ except importlib.metadata.PackageNotFoundError:
+ return
+ nums = re.findall(r"\d+", version.split("+", 1)[0])[:2]
+ if len(nums) < 2 or (int(nums[0]), int(nums[1])) >= _FQN_TO_CONFIG_SINCE:
+ return
+ try:
+ import torchao.quantization as quantization
+ except Exception: # noqa: BLE001 -- an unimportable torchao fails later with its own error
+ return
+ if not hasattr(quantization, "FqnToConfig") and hasattr(quantization, "ModuleFqnToConfig"):
+ quantization.FqnToConfig = quantization.ModuleFqnToConfig
+
+
+class _FqnAliasBeforeDiffusers(importlib.abc.MetaPathFinder):
+ """Aliases on the first ``import diffusers`` and never resolves a module itself."""
+
+ def find_spec(self, fullname, path = None, target = None):
+ if fullname == "diffusers":
+ try:
+ _alias_fqn_to_config_now()
+ except Exception: # noqa: BLE001 -- must never break the diffusers import it precedes
+ pass
+ return None
+
+
+def alias_torchao_fqn_to_config() -> None:
+ """diffusers 0.41 imports ``FqnToConfig`` from torchao unguarded; torchao < 0.15 (Studio's torch <= 2.8
+ pairing) names it ``ModuleFqnToConfig``, and 0.15 keeps ``ModuleFqnToConfig = FqnToConfig``.
+ Deferred to the first diffusers import: importing torchao here would load torch into the server
+ process and every spawn child (seconds and ~600 MB each) that never touch diffusers."""
+ if "diffusers" in sys.modules or "torchao.quantization" in sys.modules:
+ _alias_fqn_to_config_now()
+ elif not any(isinstance(f, _FqnAliasBeforeDiffusers) for f in sys.meta_path):
+ sys.meta_path.insert(0, _FqnAliasBeforeDiffusers())
+
+
def _load_torchao_nodist():
"""unsloth/_torchao_nodist.py, loaded by path: importing unsloth here would start its GPU
stack before the worker is ready. None on an unsloth that predates it."""
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index bd164746d5e..f8917c8fbb7 100644
--- a/studio/backend/core/inference/diffusion.py
+++ b/studio/backend/core/inference/diffusion.py
@@ -35,6 +35,7 @@ from pathlib import Path
from typing import Any, Callable, Optional, Sequence
from core._torchao_stub import (
+ alias_torchao_fqn_to_config,
hide_xformers_built_for_another_torch,
install_torchao_windows_rocm_stub,
install_xformers_windows_rocm_stub,
@@ -395,6 +396,7 @@ def _negative_prompt_engaged(family: DiffusionFamily, guidance: float) -> bool:
install_xformers_windows_rocm_stub()
hide_xformers_built_for_another_torch()
install_torchao_windows_rocm_stub()
+alias_torchao_fqn_to_config()
install_torchao_int_mm_patch()
diff --git a/studio/backend/core/training/diffusion_train_common.py b/studio/backend/core/training/diffusion_train_common.py
index 09f9eee3ec9..d147764d5ff 100644
--- a/studio/backend/core/training/diffusion_train_common.py
+++ b/studio/backend/core/training/diffusion_train_common.py
@@ -21,6 +21,7 @@ from pathlib import Path
from typing import Any, Callable, Optional
from core._torchao_stub import (
+ alias_torchao_fqn_to_config,
hide_xformers_built_for_another_torch,
install_torchao_windows_rocm_stub,
install_xformers_windows_rocm_stub,
@@ -42,6 +43,7 @@ from utils.paths.path_utils import drop_appledouble_metadata
install_xformers_windows_rocm_stub()
hide_xformers_built_for_another_torch()
install_torchao_windows_rocm_stub()
+alias_torchao_fqn_to_config()
# Same child: the DiT trainer's int8 base-weight quantisation goes through torchao.
install_torchao_int_mm_patch()
diff --git a/studio/backend/run.py b/studio/backend/run.py
index bdfdeb96403..d67329f01df 100644
--- a/studio/backend/run.py
+++ b/studio/backend/run.py
@@ -127,6 +127,7 @@ except ValueError as exc:
# taking diffusers/transformers with them. A stub only seeds a name nothing has imported yet, so both must
# precede the first import below. An xformers built for a newer torch fails the same import anywhere.
from core._torchao_stub import (
+ alias_torchao_fqn_to_config,
hide_xformers_built_for_another_torch,
install_torchao_windows_rocm_stub,
install_xformers_windows_rocm_stub,
@@ -135,6 +136,7 @@ from core._torchao_stub import (
install_xformers_windows_rocm_stub()
hide_xformers_built_for_another_torch()
install_torchao_windows_rocm_stub()
+alias_torchao_fqn_to_config()
# Anaconda/conda-forge Python: seed platform._sys_version_cache before imports that trigger attrs ->
# rich -> structlog -> platform crash (https://github.com/python/cpython/issues/102396).
diff --git a/studio/backend/tests/test_diffusers_prewarm.py b/studio/backend/tests/test_diffusers_prewarm.py
index d7789fa9be9..bf3959236a7 100644
--- a/studio/backend/tests/test_diffusers_prewarm.py
+++ b/studio/backend/tests/test_diffusers_prewarm.py
@@ -254,6 +254,7 @@ def test_the_windows_rocm_stubs_are_installed_before_the_import(warm, monkeypatc
(_torchao_stub, "install_xformers_windows_rocm_stub"),
(_torchao_stub, "hide_xformers_built_for_another_torch"),
(_torchao_stub, "install_torchao_windows_rocm_stub"),
+ (_torchao_stub, "alias_torchao_fqn_to_config"),
(diffusion_torchao_patches, "install_torchao_int_mm_patch"),
):
monkeypatch.setattr(mod, name, (lambda n: lambda: order.append(n))(name))
@@ -274,13 +275,14 @@ def test_the_windows_rocm_stubs_are_installed_before_the_import(warm, monkeypatc
warm.prewarm_diffusers_if_image_models_exist()
monkeypatch.undo()
- assert order[:4] == [
+ assert order[:5] == [
"install_xformers_windows_rocm_stub",
"hide_xformers_built_for_another_torch",
"install_torchao_windows_rocm_stub",
+ "alias_torchao_fqn_to_config",
"install_torchao_int_mm_patch",
], f"stubs did not run first, in the loader's order: {order}"
- assert "import" in order and order.index("import") > 3
+ assert "import" in order and order.index("import") > 4
def test_a_failed_prewarm_leaves_no_half_imported_diffusers(
diff --git a/studio/backend/tests/test_torchao_fqn_alias.py b/studio/backend/tests/test_torchao_fqn_alias.py
new file mode 100644
index 00000000000..e2dcf2b3320
--- /dev/null
+++ b/studio/backend/tests/test_torchao_fqn_alias.py
@@ -0,0 +1,137 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""torchao < 0.15 names ``FqnToConfig`` ``ModuleFqnToConfig``; diffusers 0.41 imports the new name unguarded."""
+
+from __future__ import annotations
+
+import importlib.metadata
+import sys
+import types
+
+import pytest
+
+from core import _torchao_stub
+
+
+class _ModuleFqnToConfig:
+ pass
+
+
+def fake_torchao(monkeypatch):
+ """A torchao package whose quantization module has only the pre-0.15 name, at a chosen version."""
+ pkg = types.ModuleType("torchao")
+ quant = types.ModuleType("torchao.quantization")
+ quant.ModuleFqnToConfig = _ModuleFqnToConfig
+ pkg.quantization = quant
+ monkeypatch.setitem(sys.modules, "torchao", pkg)
+ monkeypatch.setitem(sys.modules, "torchao.quantization", quant)
+
+ def use(version):
+ def _version(name):
+ if name != "torchao":
+ return importlib.metadata.version(name)
+ if version is None:
+ raise importlib.metadata.PackageNotFoundError(name)
+ return version
+
+ monkeypatch.setattr(_torchao_stub.importlib.metadata, "version", _version)
+ return quant
+
+ return use
+
+
[email protected]("version", ["0.14.0", "0.14.1", "0.13.0", "0.14.0+cu126", "0.14.0.dev20251001"])
+def test_an_old_torchao_gains_the_new_name(fake_torchao, version):
+ quant = fake_torchao(version)
+ _torchao_stub.alias_torchao_fqn_to_config()
+ from torchao.quantization import FqnToConfig
+
+ assert FqnToConfig is quant.ModuleFqnToConfig
+ _torchao_stub.alias_torchao_fqn_to_config() # idempotent
+ assert quant.FqnToConfig is quant.ModuleFqnToConfig
+
+
[email protected]("version", ["0.15.0", "0.17.0+cu130", "0.18.0", "1.0.0"])
+def test_a_new_torchao_is_left_alone(fake_torchao, version):
+ quant = fake_torchao(version)
+ _torchao_stub.alias_torchao_fqn_to_config()
+ assert not hasattr(quant, "FqnToConfig")
+
+
+def test_a_new_torchao_is_not_even_imported(monkeypatch):
+ monkeypatch.setattr(sys, "meta_path", list(sys.meta_path))
+ monkeypatch.setattr(_torchao_stub.importlib.metadata, "version", lambda name: "0.18.0")
+ monkeypatch.delitem(sys.modules, "torchao", raising = False)
+ monkeypatch.delitem(sys.modules, "torchao.quantization", raising = False)
+ monkeypatch.setitem(sys.modules, "diffusers", types.ModuleType("diffusers"))
+ _torchao_stub.alias_torchao_fqn_to_config()
+ assert "torchao.quantization" not in sys.modules
+
+
+def _drop_diffusers_and_torchao(monkeypatch):
+ monkeypatch.setattr(sys, "meta_path", list(sys.meta_path))
+ for name in [n for n in sys.modules if n.split(".")[0] in ("diffusers", "torchao")]:
+ monkeypatch.delitem(sys.modules, name)
+
+
+def test_an_old_torchao_is_aliased_on_the_first_diffusers_import_not_before(monkeypatch, tmp_path):
+ """run.py and every spawn child call this; importing torchao there would load torch for nothing."""
+ _drop_diffusers_and_torchao(monkeypatch)
+ pkg = tmp_path / "torchao"
+ (pkg / "quantization").mkdir(parents = True)
+ (pkg / "__init__.py").write_text("")
+ (pkg / "quantization" / "__init__.py").write_text("class ModuleFqnToConfig:\n pass\n")
+ (tmp_path / "diffusers").mkdir()
+ (tmp_path / "diffusers" / "__init__.py").write_text("from torchao.quantization import FqnToConfig\n")
+ monkeypatch.syspath_prepend(str(tmp_path))
+ monkeypatch.setattr(_torchao_stub.importlib.metadata, "version", lambda name: "0.14.0")
+
+ _torchao_stub.alias_torchao_fqn_to_config()
+ _torchao_stub.alias_torchao_fqn_to_config()
+ assert "torchao" not in sys.modules
+ assert sum(isinstance(f, _torchao_stub._FqnAliasBeforeDiffusers) for f in sys.meta_path) == 1
+
+ import diffusers
+
+ assert diffusers.FqnToConfig is sys.modules["torchao.quantization"].ModuleFqnToConfig
+
+
+def test_a_failing_alias_never_breaks_the_diffusers_import(monkeypatch):
+ _drop_diffusers_and_torchao(monkeypatch)
+
+ def boom():
+ raise RuntimeError("unreadable metadata")
+
+ monkeypatch.setattr(_torchao_stub, "_alias_fqn_to_config_now", boom)
+ assert _torchao_stub._FqnAliasBeforeDiffusers().find_spec("diffusers") is None
+
+
+def test_absent_or_stubbed_torchao_is_a_no_op(fake_torchao, monkeypatch):
+ quant = fake_torchao(None)
+ _torchao_stub.alias_torchao_fqn_to_config()
+ assert not hasattr(quant, "FqnToConfig")
+ fake_torchao("0.14.0")
+ monkeypatch.setattr(_torchao_stub, "is_stubbed", lambda name: name == "torchao")
+ _torchao_stub.alias_torchao_fqn_to_config()
+ assert not hasattr(quant, "FqnToConfig")
+
+
+def test_an_existing_fqn_to_config_is_kept(fake_torchao):
+ quant = fake_torchao("0.14.0")
+ sentinel = type("FqnToConfig", (), {})
+ quant.FqnToConfig = sentinel
+ _torchao_stub.alias_torchao_fqn_to_config()
+ assert quant.FqnToConfig is sentinel
+
+
[email protected]("module", ["run", "core.inference.diffusion", "core.training.diffusion_train_common"])
+def test_every_diffusers_importer_aliases_after_the_rocm_stub(module):
+ """Static order check: each module-level hook block runs the alias right after the torchao stub."""
+ import importlib.util
+ from pathlib import Path
+
+ spec = importlib.util.find_spec(module)
+ src = Path(spec.origin).read_text(encoding = "utf-8")
+ assert "\ninstall_torchao_windows_rocm_stub()\nalias_torchao_fqn_to_config()\n" in src
diff --git a/studio/backend/utils/torch_warmup.py b/studio/backend/utils/torch_warmup.py
index 7bfae614159..fba6cf2547c 100644
--- a/studio/backend/utils/torch_warmup.py
+++ b/studio/backend/utils/torch_warmup.py
@@ -683,6 +683,7 @@ def prewarm_diffusers_if_image_models_exist() -> bool:
# On Windows ROCm diffusers reaches xformers and torchao, both landing on an
# absent distributed backend, so any first importer owes these stubs.
from core._torchao_stub import ( # noqa: PLC0415
+ alias_torchao_fqn_to_config,
hide_xformers_built_for_another_torch,
install_torchao_windows_rocm_stub,
install_xformers_windows_rocm_stub,
@@ -694,6 +695,7 @@ def prewarm_diffusers_if_image_models_exist() -> bool:
install_xformers_windows_rocm_stub()
hide_xformers_built_for_another_torch()
install_torchao_windows_rocm_stub()
+ alias_torchao_fqn_to_config()
install_torchao_int_mm_patch()
except Exception as exc: # noqa: BLE001 -- importing unprotected is the hazard; skip
logger.debug("diffusers prewarm skipped: stubs unavailable: %r", exc)