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.

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.py
new file mode 100644
index 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.py
index 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 re
import sys
import 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 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)
+ 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)}")