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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
Stop fix_executorch from hiding an installed torchtune (#14375)
Daniel Han4ff83b553c90
diff --git a/tests/test_executorch_torchtune_shim.py b/tests/test_executorch_torchtune_shim.pynew file mode 100644index 00000000000..6b708f21c4a--- /dev/null+++ b/tests/test_executorch_torchtune_shim.py@@ -0,0 +1,242 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.++"""fix_executorch must never hide an installed torchtune (fake packages, fresh interpreters)."""++import json+import os+import subprocess+import sys+import textwrap+from pathlib import Path++import pytest++ROOT = Path(__file__).resolve().parents[1]+IMPORT_FIXES = ROOT / "unsloth" / "import_fixes.py"++EXECUTORCH_MODELS_INIT = """\+# Copyright (c) Meta Platforms, Inc. and affiliates.++from enum import Enum+++class Model(str, Enum):+ Llama = "llama"+"""++LEGACY_MAPPED_KEY_IMPORT = "from torchtune.models.convert_weights import get_mapped_key\n"+++def _make_executorch(root: Path, legacy_import: bool = True) -> Path:+ models = root / "executorch" / "examples" / "models"+ (models / "qwen2_5").mkdir(parents = True)+ (root / "executorch" / "__init__.py").write_text("")+ (root / "executorch" / "examples" / "__init__.py").write_text("")+ (models / "__init__.py").write_text(EXECUTORCH_MODELS_INIT)+ (models / "qwen2_5" / "__init__.py").write_text("")+ src = (+ LEGACY_MAPPED_KEY_IMPORT+ if legacy_import+ else ("from executorch.examples.models.checkpoint import get_mapped_key\n")+ )+ (models / "qwen2_5" / "convert_weights.py").write_text(src)+ return models / "__init__.py"+++def _make_real_torchtune(root: Path) -> None:+ cw = root / "torchtune" / "models"+ cw.mkdir(parents = True)+ (root / "torchtune" / "__init__.py").write_text("REAL = True\n")+ (cw / "__init__.py").write_text("")+ (cw / "convert_weights.py").write_text(+ "def get_mapped_key(key, mapping_dict):\n return 'real'\n"+ "def tune_to_meta(sd):\n return sd\n"+ "def hf_to_tune(sd, **kw):\n return sd\n"+ )+++# An installed torchtune must not leak into the "absent" cases: only the fake packages under `path` count.+_HIDE_SITE_TORCHTUNE = (+ "import os as _os, sys as _sys\n"+ "_sys.path[:] = [_p for _p in _sys.path if _p == {path!r} or not "+ "_os.path.exists(_os.path.join(_p or '.', 'torchtune'))]\n"+)+++def _run(code: str, path: Path) -> dict:+ env = dict(os.environ)+ env["PYTHONPATH"] = str(path)+ out = subprocess.run(+ [sys.executable, "-c", _HIDE_SITE_TORCHTUNE.format(path = str(path)) + textwrap.dedent(code)],+ env = env,+ capture_output = True,+ text = True,+ timeout = 120,+ cwd = str(path),+ )+ assert out.returncode == 0, out.stderr+ return json.loads(out.stdout.strip().splitlines()[-1])+++def _apply_fix(path: Path) -> None:+ _run(+ f"""+ import importlib.util, json+ s = importlib.util.spec_from_file_location("_uif", {str(IMPORT_FIXES)!r})+ m = importlib.util.module_from_spec(s)+ s.loader.exec_module(m)+ m.fix_executorch()+ print(json.dumps({{}}))+ """,+ path,+ )+++PROBE = """+import json, sys+{pre}+import executorch.examples.models+tt = sys.modules.get("torchtune")+from torchtune.models.convert_weights import get_mapped_key+import torchtune+res = {{+ "real": getattr(torchtune, "REAL", False),+ "mapped": get_mapped_key("layers.3.attention.wq.weight",+ {{"layers.{{}}.attention.wq.weight": "model.layers.{{}}.q"}}),+}}+try:+ from torchtune.models import convert_weights+ convert_weights.tune_to_meta+ res["tune_to_meta"] = "ok"+except AttributeError as e:+ res["tune_to_meta"] = "missing: " + str(e)+print(json.dumps(res))+"""+++def test_torchtune_absent_gets_stub(tmp_path):+ _make_executorch(tmp_path)+ _apply_fix(tmp_path)+ res = _run(PROBE.format(pre = ""), tmp_path)+ assert res["real"] is False+ assert res["mapped"] == "model.layers.3.q"+ assert "torchtune is not installed" in res["tune_to_meta"]+++def test_torchtune_installed_is_not_hidden(tmp_path):+ _make_executorch(tmp_path)+ _make_real_torchtune(tmp_path)+ _apply_fix(tmp_path)+ res = _run(PROBE.format(pre = ""), tmp_path)+ assert res["real"] is True+ assert res["mapped"] == "real"+ assert res["tune_to_meta"] == "ok"+++def test_torchtune_imported_first_is_kept(tmp_path):+ _make_executorch(tmp_path)+ _make_real_torchtune(tmp_path)+ _apply_fix(tmp_path)+ res = _run(PROBE.format(pre = "import torchtune.models.convert_weights"), tmp_path)+ assert res["real"] is True and res["tune_to_meta"] == "ok"+++def test_torchtune_installed_after_patch(tmp_path):+ # Patch written while torchtune was absent; user installs torchtune later.+ _make_executorch(tmp_path)+ _apply_fix(tmp_path)+ _make_real_torchtune(tmp_path)+ res = _run(PROBE.format(pre = ""), tmp_path)+ assert res["real"] is True and res["tune_to_meta"] == "ok"+++def test_idempotent(tmp_path):+ init = _make_executorch(tmp_path)+ _apply_fix(tmp_path)+ once = init.read_text()+ assert once != EXECUTORCH_MODELS_INIT+ _apply_fix(tmp_path)+ _apply_fix(tmp_path)+ assert init.read_text() == once+++def test_no_patch_when_executorch_has_own_get_mapped_key(tmp_path):+ init = _make_executorch(tmp_path, legacy_import = False)+ _make_real_torchtune(tmp_path)+ _apply_fix(tmp_path)+ assert init.read_text() == EXECUTORCH_MODELS_INIT+ res = _run(PROBE.format(pre = ""), tmp_path)+ assert res["real"] is True++[email protected]("legacy_import", [True, False])+def test_repairs_legacy_unguarded_block(tmp_path, legacy_import):+ init = _make_executorch(tmp_path, legacy_import = legacy_import)+ _make_real_torchtune(tmp_path)+ s = __import__("importlib.util").util.spec_from_file_location("_uif_t", IMPORT_FIXES)+ m = __import__("importlib.util").util.module_from_spec(s)+ s.loader.exec_module(m)+ legacy = m._LEGACY_EXECUTORCH_TORCHTUNE_SHIM+ init.write_text(+ EXECUTORCH_MODELS_INIT.replace(+ "from enum import Enum\n\n", "from enum import Enum\n\n" + legacy, 1+ )+ )+ assert _run(PROBE.format(pre = ""), tmp_path)["real"] is False+ _apply_fix(tmp_path)+ assert legacy not in init.read_text()+ if not legacy_import:+ assert init.read_text() == EXECUTORCH_MODELS_INIT+ res = _run(PROBE.format(pre = ""), tmp_path)+ assert res["real"] is True and res["tune_to_meta"] == "ok"++[email protected]("editable", [False, True])+def test_legacy_stub_already_imported_is_dropped(tmp_path, editable):+ # An old patched executorch imported before Unsloth in the same process: the stub is already in sys.modules.+ init = _make_executorch(tmp_path)+ site = tmp_path / "editable" if editable else tmp_path+ site.mkdir(exist_ok = True)+ _make_real_torchtune(site)+ # PEP 660 editable installs resolve through a meta path finder, not a sys.path entry.+ finder = (+ f"""+ import importlib.machinery+ class _Editable:+ @classmethod+ def find_spec(cls, name, path = None, target = None):+ if name == "torchtune":+ return importlib.machinery.PathFinder.find_spec(name, [{str(site)!r}])+ sys.meta_path.append(_Editable)+ """+ if editable+ else ""+ )+ s = __import__("importlib.util").util.spec_from_file_location("_uif_t2", IMPORT_FIXES)+ m = __import__("importlib.util").util.module_from_spec(s)+ s.loader.exec_module(m)+ init.write_text(+ EXECUTORCH_MODELS_INIT.replace(+ "from enum import Enum\n\n",+ "from enum import Enum\n\n" + m._LEGACY_EXECUTORCH_TORCHTUNE_SHIM,+ 1,+ )+ )+ res = _run(+ f"""+ import importlib.util, json, sys+ import executorch.examples.models+ assert getattr(sys.modules["torchtune"], "REAL", False) is False+ {textwrap.indent(textwrap.dedent(finder), " " * 8).strip()}+ s = importlib.util.spec_from_file_location("_uif", {str(IMPORT_FIXES)!r})+ m = importlib.util.module_from_spec(s)+ s.loader.exec_module(m)+ m.fix_executorch()+ import torchtune+ from torchtune.models import convert_weights+ print(json.dumps({{"real": getattr(torchtune, "REAL", False), "hf_to_tune": hasattr(convert_weights, "hf_to_tune")}}))+ """,+ tmp_path,+ )+ assert res == {"real": True, "hf_to_tune": True}diff --git a/unsloth/import_fixes.py b/unsloth/import_fixes.pyindex 49fd819d8ae..633234460a7 100644--- a/unsloth/import_fixes.py+++ b/unsloth/import_fixes.py@@ -6953,35 +6953,77 @@ def fix_openenv_no_vllm():logger.info(f"Unsloth: Failed patching TRL OpenEnv with error = {str(e)}")-# Fix Exeuctorch needing get_mapped_key-def fix_executorch():- spec = importlib.util.find_spec("executorch")- if spec is None:- return- executorch_location = spec.origin- if executorch_location is None:- executorch_location = spec.submodule_search_locations[0]- else:- executorch_location = os.path.split(executorch_location)[0]- executorch = Path(executorch_location) / "examples" / "models" / "__init__.py"- if not executorch.exists():- return+# Verbatim block older Unsloth wrote into executorch; it hid a real torchtune, so we repair it.+_LEGACY_EXECUTORCH_TORCHTUNE_SHIM = textwrap.dedent(+ r"""+ import sys+ import types+ import re+ from typing import Any, Optional+ def get_mapped_key(key: str, mapping_dict: dict[str, str]) -> str:+ try:+ # Checks if there is a layer # in the key+ if any(k.isdigit() for k in key.split(".")):+ # Replace layer number with "{}" to create key for lookup+ abstract_key = re.sub(r"(\.\d+)", ".{}", key)+ layer_num = re.search(r"\d+", key).group(0)+ new_key = mapping_dict[abstract_key]+ new_key = new_key.format(layer_num)+ else:+ new_key = mapping_dict[key]+ except KeyError as e:+ raise Exception(+ f'Error converting the state dict. Found unexpected key: "{key}". '+ "Please make sure you're loading a checkpoint with the right format. "+ ) from e++ return new_key++ torchtune = types.ModuleType("torchtune")+ torchtune.__path__ = []+ models = types.ModuleType("torchtune.models")+ models.__path__ = []+ convert_weights = types.ModuleType("torchtune.models.convert_weights")+ convert_weights.get_mapped_key = get_mapped_key+ torchtune.models = models+ models.convert_weights = convert_weights+ sys.modules["torchtune"] = torchtune+ sys.modules["torchtune.models"] = models+ sys.modules["torchtune.models.convert_weights"] = convert_weights+ """+)- try:- what = r"""+_EXECUTORCH_TORCHTUNE_SHIM_MARKER = "# Unsloth: torchtune get_mapped_key shim v2"++# Stub only when torchtune is not installed or imported.+_EXECUTORCH_TORCHTUNE_SHIM = _EXECUTORCH_TORCHTUNE_SHIM_MARKER + textwrap.dedent(+ r"""+ def _unsloth_torchtune_shim():+ import importlib.machinery+ import importlib.util+ import reimport sysimport types- import re- from typing import Any, Optional- def get_mapped_key(key: str, mapping_dict: dict[str, str]) -> str:++ if "torchtune" in sys.modules:+ return+ try:+ if importlib.util.find_spec("torchtune") is not None:+ return+ except (ImportError, ValueError):+ return++ def get_mapped_key(key, mapping_dict):try:- # Checks if there is a layer # in the keyif any(k.isdigit() for k in key.split(".")):- # Replace layer number with "{}" to create key for lookupabstract_key = re.sub(r"(\.\d+)", ".{}", key)- layer_num = re.search(r"\d+", key).group(0)- new_key = mapping_dict[abstract_key]- new_key = new_key.format(layer_num)+ match = re.search(r"\.(\d+)", key)+ if match is None:+ raise Exception(+ f'Error converting the state dict. Could not find layer number in key: "{key}". '+ "Please make sure you're loading a checkpoint with the right format. "+ )+ new_key = mapping_dict[abstract_key].format(match.group(1))else:new_key = mapping_dict[key]except KeyError as e:@@ -6989,32 +7031,109 @@ def fix_executorch():f'Error converting the state dict. Found unexpected key: "{key}". '"Please make sure you're loading a checkpoint with the right format. ") from e-return new_key- torchtune = types.ModuleType("torchtune")- torchtune.__path__ = []- models = types.ModuleType("torchtune.models")- models.__path__ = []- convert_weights = types.ModuleType("torchtune.models.convert_weights")- convert_weights.get_mapped_key = get_mapped_key- torchtune.models = models- models.convert_weights = convert_weights- sys.modules["torchtune"] = torchtune- sys.modules["torchtune.models"] = models- sys.modules["torchtune.models.convert_weights"] = convert_weights- """- what = textwrap.dedent(what)+ def _missing(name):+ raise AttributeError(+ f"torchtune.models.convert_weights.{name} is unavailable: torchtune is not "+ "installed (only a get_mapped_key stub is provided). Install torchtune."+ )- with open(executorch, "r+", encoding = "utf-8") as f:- text = f.read()- bad = "from enum import Enum\n"- if bad in text and what not in text:- text = text.replace(bad + "\n", bad + "\n" + what)- f.seek(0)+ names = ("torchtune", "torchtune.models", "torchtune.models.convert_weights")+ mods = []+ for i, name in enumerate(names):+ mod = types.ModuleType(name)+ is_pkg = i < 2+ mod.__spec__ = importlib.machinery.ModuleSpec(name, None, is_package = is_pkg)+ if is_pkg:+ mod.__path__ = []+ mods.append(mod)+ mods[2].get_mapped_key = get_mapped_key+ mods[2].__getattr__ = _missing+ mods[0].models = mods[1]+ mods[1].convert_weights = mods[2]+ for name, mod in zip(names, mods):+ sys.modules.setdefault(name, mod)++ _unsloth_torchtune_shim()+ del _unsloth_torchtune_shim+ """+)+++def _executorch_needs_torchtune_get_mapped_key(models_dir):+ # Newer ExecuTorch ships its own get_mapped_key; only old imports need the stub.+ needle = "from torchtune.models.convert_weights import get_mapped_key"+ try:+ for path in Path(models_dir).glob("*/*.py"):+ try:+ if needle in path.read_text(encoding = "utf-8", errors = "ignore"):+ return True+ except OSError:+ continue+ except OSError:+ return False+ return False+++# Fix Executorch needing torchtune's get_mapped_key when torchtune is absent+def _drop_loaded_legacy_torchtune_stub():+ # An old patched executorch imported before Unsloth already put the legacy stub in sys.modules; it has no+ # file and no hf_to_tune. Drop it when a real torchtune is installed so the next import finds the package.+ stub = sys.modules.get("torchtune")+ if (+ stub is None+ or getattr(stub, "__file__", None) is not None+ or getattr(stub, "__spec__", None) is not None+ ):+ return+ convert_weights = sys.modules.get("torchtune.models.convert_weights")+ if convert_weights is None or not hasattr(convert_weights, "get_mapped_key"):+ return+ if hasattr(convert_weights, "hf_to_tune"):+ return+ names = ("torchtune.models.convert_weights", "torchtune.models", "torchtune")+ saved = {name: sys.modules.pop(name) for name in names if name in sys.modules}+ try:+ # Full import machinery, so editable (meta path finder) installs are seen too.+ found = importlib.util.find_spec("torchtune") is not None+ except (ImportError, ValueError):+ found = False+ if not found:+ sys.modules.update(saved)+++def fix_executorch():+ spec = importlib.util.find_spec("executorch")+ if spec is None:+ return+ executorch_location = spec.origin+ if executorch_location is None:+ if not spec.submodule_search_locations:+ return+ executorch_location = list(spec.submodule_search_locations)[0]+ else:+ executorch_location = os.path.split(executorch_location)[0]+ executorch = Path(executorch_location) / "examples" / "models" / "__init__.py"+ if not executorch.exists():+ return++ try:+ with open(executorch, "r", encoding = "utf-8") as f:+ original = f.read()+ text = original+ needs_shim = _executorch_needs_torchtune_get_mapped_key(executorch.parent)+ legacy = _LEGACY_EXECUTORCH_TORCHTUNE_SHIM+ if legacy in text:+ text = text.replace(legacy, _EXECUTORCH_TORCHTUNE_SHIM if needs_shim else "")+ anchor = "from enum import Enum\n\n"+ if needs_shim and _EXECUTORCH_TORCHTUNE_SHIM_MARKER not in text and anchor in text:+ text = text.replace(anchor, anchor + _EXECUTORCH_TORCHTUNE_SHIM, 1)+ if text != original:+ with open(executorch, "w", encoding = "utf-8") as f:f.write(text)- f.truncate()- logger.info("Unsloth: Patching Executorch to fix get_mapped_key")+ logger.info("Unsloth: Patching Executorch to fix get_mapped_key")+ _drop_loaded_legacy_torchtune_stub()except Exception as e:logger.info(f"Unsloth: Failed Executorch with error = {str(e)}")