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
feat(studio): Mac adapter-format option for LoRA export, with GGUF adapters on macOS (#7539)
Long Yixing46161d7de771
diff --git a/studio/backend/core/export/export.py b/studio/backend/core/export/export.pyindex c53090c8315..3b94d2922f5 100644--- a/studio/backend/core/export/export.py+++ b/studio/backend/core/export/export.py@@ -27,7 +27,7 @@ except Exception as _unsloth_exc:_UNSLOTH_IMPORT_ERROR = _unsloth_excfrom huggingface_hub import HfApi, ModelCard-from hub.utils.hf_tokens import HfTokenArg, is_anonymous, normalize_token+from hub.utils.hf_tokens import HfTokenArg, apply_token_to_child_env, is_anonymous, normalize_tokenfrom utils.hardware import clear_gpu_cachefrom utils.models import is_vision_model, get_base_model_from_lora@@ -54,6 +54,33 @@ if not _IS_MLX:logger = get_logger(__name__)+_ADAPTER_WEIGHT_NAMES = {+ "mlx": frozenset({"adapters.safetensors"}),+ "peft": frozenset({"adapter_model.safetensors", "adapter_model.bin"}),+}+_ZOO_UPGRADE_MESSAGE = (+ "PEFT adapter conversion requires an updated unsloth-zoo. Upgrade "+ "unsloth-zoo, then retry adapter_format='peft' (or GGUF adapter export)."+)+++def _other_adapter_weight_names(resolved_format: str) -> frozenset:+ return _ADAPTER_WEIGHT_NAMES["peft" if resolved_format == "mlx" else "mlx"]+++def _resolve_adapter_format(adapter_format: Optional[str]) -> Tuple[Optional[str], Optional[str]]:+ """Return (format, error); omission resolves to the platform's native format."""+ if adapter_format is None:+ return ("mlx" if _IS_MLX else "peft"), None+ if adapter_format not in _ADAPTER_WEIGHT_NAMES:+ return None, f"Invalid adapter_format '{adapter_format}'. Choose 'mlx' or 'peft'."+ if adapter_format == "mlx" and not _IS_MLX:+ return None, (+ "adapter_format='mlx' is only available on Apple-silicon MLX "+ "servers; this server exports the native PEFT format."+ )+ return adapter_format, None+def _load_in_4bit_kwargs(load_in_4bit: bool) -> dict:# True is the loaders' default; passing it reads as an explicit request to requantize fp8 checkpoints to NF4.@@ -889,6 +916,8 @@ class ExportBackend:f"Restored Hub model identity for legacy adapter export: {restored_repo_id}")+ # The MLX GGUF LoRA converter honors the approved load decision.+ self.trust_remote_code = bool(trust_remote_code)self.current_model = modelself.current_tokenizer = tokenizerself.current_checkpoint = checkpoint_path@@ -1656,6 +1685,194 @@ class ExportBackend:)return False, f"GGUF export failed: {str(e)}", None+ def _save_mlx_adapter(+ self,+ destination: str,+ resolved_format: str,+ gguf_outtype: Optional[str] = None,+ hf_token: HfTokenArg = None,+ ) -> None:+ """Save the loaded MLX adapter as mlx or peft, plus a GGUF LoRA when gguf_outtype is set."""+ if resolved_format == "mlx":+ self.current_model.save_lora_adapters(destination)+ self.current_tokenizer.save_pretrained(destination)+ return+ saver = getattr(self.current_model, "save_lora_adapters", None)+ if not _supports_kwarg(saver, "adapter_format"):+ raise RuntimeError(_ZOO_UPGRADE_MESSAGE)+ # The zoo converter refuses an existing path; stage fresh so a repeat export overwrites.+ parent = Path(destination).parent+ ensure_dir(parent)+ with tempfile.TemporaryDirectory(prefix = _STAGING_PREFIX, dir = parent) as tmp_dir:+ staged = os.path.join(tmp_dir, "adapter")+ saver(staged, adapter_format = "peft")+ self.current_tokenizer.save_pretrained(staged)+ if gguf_outtype:+ self._convert_peft_dir_to_gguf(staged, gguf_outtype, hf_token)+ ensure_dir(Path(destination))+ for name in os.listdir(staged):+ src, dst = os.path.join(staged, name), os.path.join(destination, name)+ if os.path.isdir(src):+ shutil.copytree(src, dst, dirs_exist_ok = True)+ else:+ os.replace(src, dst)++ def _convert_peft_dir_to_gguf(+ self, save_directory: str, outtype: str, hf_token: HfTokenArg+ ) -> None:+ """Convert a PEFT adapter with llama.cpp's convert_lora_to_gguf.py, as the CUDA path does."""+ import importlib.util+ import subprocess+ import sys as _sys++ with open(os.path.join(save_directory, "adapter_config.json"), "r", encoding = "utf-8") as f:+ peft_cfg = json.load(f)+ rejects = []+ if peft_cfg.get("alpha_pattern"):+ rejects.append("per-module alpha values (GGUF LoRA stores one global alpha)")+ if peft_cfg.get("use_rslora") and peft_cfg.get("rank_pattern"):+ rejects.append("rsLoRA with per-module ranks (bakes to per-module alphas)")+ if peft_cfg.get("use_dora"):+ rejects.append("DoRA magnitudes (no GGUF LoRA representation)")+ if peft_cfg.get("modules_to_save") or getattr(+ self.current_model, "_unsloth_full_state_modules", None+ ):+ rejects.append("full-module state (modules_to_save or replaced embeddings)")+ if peft_cfg.get("target_parameters"):+ rejects.append("expert-parameter adapters (llama.cpp has no expert handling)")+ if rejects:+ raise RuntimeError(+ "This adapter cannot be exported as a GGUF LoRA: "+ + "; ".join(rejects)+ + ". Export the PEFT safetensors adapter instead."+ )++ if importlib.util.find_spec("torch") is None:+ raise RuntimeError(+ "GGUF adapter export needs the 'torch' Python package for "+ "llama.cpp's converter; install it and retry."+ )++ from unsloth_zoo import llama_cpp as _zoo_llama_cpp++ default_dir = os.path.normpath(_zoo_llama_cpp.LLAMA_CPP_DEFAULT_DIR)+ source_dir = os.path.join(os.path.dirname(default_dir), "llama.cpp-source")+ # A user-set scripts dir is authoritative and is checked before any network revision lookup.+ pinned_dir = os.environ.get("UNSLOTH_LLAMA_CPP_SCRIPTS_DIR", "").strip()+ if pinned_dir:+ converter = os.path.join(os.path.expanduser(pinned_dir), "convert_lora_to_gguf.py")+ if not os.path.exists(converter):+ raise RuntimeError(+ f"UNSLOTH_LLAMA_CPP_SCRIPTS_DIR={pinned_dir} has no convert_lora_to_gguf.py; point it "+ "at a full llama.cpp checkout or unset it."+ )+ elif os.path.exists(os.path.join(default_dir, "convert_lora_to_gguf.py")):+ converter = os.path.join(default_dir, "convert_lora_to_gguf.py")+ else:+ # Pinned to the installed binaries' revision (else the latest release).+ try:+ _repo, tag = _zoo_llama_cpp._resolve_converter_revision(default_dir)+ except Exception:+ tag = None+ tag = tag.split("-mix-")[0] if tag else None+ if tag:+ source_dir = f"{source_dir}-{tag}"+ converter = os.path.join(source_dir, "convert_lora_to_gguf.py")+ if not os.path.exists(converter):+ converter = None+ if converter is None:+ if not getattr(_zoo_llama_cpp, "_converter_network_allowed", lambda: True)():+ raise RuntimeError(+ "GGUF adapter export needs llama.cpp's convert_lora_to_gguf.py, which is not "+ f"installed, and offline mode forbids cloning it; clone llama.cpp into {source_dir}."+ )+ if not getattr(_zoo_llama_cpp, "_auto_install_enabled", lambda: True)():+ raise RuntimeError(+ "GGUF adapter export needs a llama.cpp source checkout and automatic "+ f"installation was declined (UNSLOTH_AUTO_INSTALL=0); clone llama.cpp into {source_dir}."+ )+ # Not install_llama_cpp: it probes apt-get even when only cloning, which fails on macOS.+ ensure_dir(Path(source_dir).parent)+ with tempfile.TemporaryDirectory(dir = Path(source_dir).parent) as tmp_dir:+ clone = os.path.join(tmp_dir, "llama.cpp")+ subprocess.run(+ [+ "git",+ "clone",+ "--depth",+ "1",+ *(["--branch", tag] if tag else []),+ "https://github.com/ggml-org/llama.cpp",+ clone,+ ],+ check = True,+ capture_output = True,+ text = True,+ )+ if not os.path.exists(source_dir):+ os.replace(clone, source_dir)+ converter = os.path.join(source_dir, "convert_lora_to_gguf.py")+ if not os.path.exists(converter):+ raise RuntimeError(+ f"convert_lora_to_gguf.py is missing from the llama.cpp clone at {source_dir}."+ )+ if importlib.util.find_spec("gguf") is None and not os.path.isdir(+ os.path.join(os.path.dirname(converter), "gguf-py")+ ):+ raise RuntimeError(+ "GGUF adapter export needs the 'gguf' Python package (or a "+ "full llama.cpp checkout with gguf-py); install it and retry."+ )++ base_model_id = peft_cfg.get("base_model_name_or_path") or getattr(+ self.current_model, "_hf_repo", None+ )+ if not base_model_id:+ raise RuntimeError(+ "Could not determine the adapter's base model for GGUF "+ "conversion (no base_model_name_or_path)."+ )+ model_name = str(base_model_id).replace("\\", "/").rstrip("/").split("/")[-1] or "model"+ out_gguf = os.path.join(save_directory, f"{model_name}-lora-{outtype}.gguf")+ cmd = [+ _sys.executable,+ converter,+ save_directory,+ "--outfile",+ out_gguf,+ "--outtype",+ outtype,+ ]+ # The snapshot the model was loaded from carries the adapter's pinned base revision.+ loaded_base = next(+ (+ str(p)+ for p in (+ getattr(self.current_model, "_config_src_path", None),+ getattr(self.current_model, "_src_path", None),+ base_model_id,+ )+ if isinstance(p, (str, os.PathLike))+ and os.path.isfile(os.path.join(str(p), "config.json"))+ ),+ None,+ )+ if loaded_base:+ cmd += ["--base", loaded_base]+ else:+ cmd += ["--base-model-id", str(base_model_id)]+ if getattr(self, "trust_remote_code", False):+ cmd.append("--trust-remote-code")+ env = os.environ.copy()+ apply_token_to_child_env(env, normalize_token(hf_token))+ logger.info(f"Converting adapter at '{save_directory}' to GGUF -> '{out_gguf}'")+ result = subprocess.run(cmd, env = env, capture_output = True, text = True)+ if result.returncode != 0:+ raise RuntimeError(+ f"LoRA -> GGUF conversion failed (exit {result.returncode}): "+ + (result.stderr or result.stdout or "").strip()[-2000:]+ )+def export_lora_adapter(self,save_directory: str,@@ -1665,12 +1882,14 @@ class ExportBackend:private: bool = False,gguf: bool = False,gguf_outtype: str = "q8_0",+ adapter_format: Optional[str] = None,) -> Tuple[bool, str, Optional[str]]:"""Export the LoRA adapter only, not merged.``gguf`` also converts the adapter to a GGUF LoRA file (llama.cpp convert_lora_to_gguf.py),loadable with `llama-cli --lora ...`; ``gguf_outtype`` is its output float type, one of- q8_0/f16/bf16/f32.+ q8_0/f16/bf16/f32. ``adapter_format`` is 'mlx' or 'peft' (MLX servers only offer both);+ omitted resolves to the platform's native format."""if not _export_runtime_available():return False, _export_runtime_message(), None@@ -1680,15 +1899,20 @@ class ExportBackend:if not self.is_peft:return False, "This is not a PEFT model. No adapter to export.", None+ resolved_format, format_error = _resolve_adapter_format(adapter_format)+ if format_error:+ return False, format_error, None+_GGUF_LORA_OUTTYPES = ("q8_0", "f16", "bf16", "f32")if gguf:- if _IS_MLX:+ if adapter_format == "mlx":return (False,- "GGUF LoRA adapter export is not supported on macOS/MLX. "- "Use the safetensors adapter instead.",+ "GGUF LoRA files are built from a PEFT-format adapter; "+ "omit adapter_format or use 'peft' with gguf=True.",None,)+ resolved_format = "peft"# convert_lora_to_gguf.py reads only the standard lora_A/lora_B delta and ignores DoRA's# lora_magnitude_vector, so a DoRA export silently drops magnitude rescaling._peft_config = getattr(self.current_model, "peft_config", {}).get("default")@@ -1709,18 +1933,27 @@ class ExportBackend:f"Choose one of {', '.join(_GGUF_LORA_OUTTYPES)}.",None,)- # getattr so an older build without save_pretrained_gguf returns a clean message instead of a generic 500.- _save_gguf_fn = getattr(self.current_model, "save_pretrained_gguf", None)- if _save_gguf_fn is None or not _supports_kwarg(_save_gguf_fn, "save_method"):- return (- False,- "This Unsloth build does not support GGUF LoRA adapter export. "- "Upgrade unsloth and unsloth_zoo, or export the safetensors adapter.",- None,- )+ if _IS_MLX:+ if not _supports_kwarg(+ getattr(self.current_model, "save_lora_adapters", None), "adapter_format"+ ):+ return False, _ZOO_UPGRADE_MESSAGE, None+ else:+ # getattr so an older build without save_pretrained_gguf returns a clean message instead of a generic 500.+ _save_gguf_fn = getattr(self.current_model, "save_pretrained_gguf", None)+ if _save_gguf_fn is None or not _supports_kwarg(_save_gguf_fn, "save_method"):+ return (+ False,+ "This Unsloth build does not support GGUF LoRA adapter export. "+ "Upgrade unsloth and unsloth_zoo, or export the safetensors adapter.",+ None,+ )def save_lora_gguf(directory):# Writes the adapter files plus "<base>-lora-<outtype>.gguf".+ if _IS_MLX:+ self._save_mlx_adapter(directory, "peft", gguf_outtype = outtype, hf_token = hf_token)+ returnself.current_model.save_pretrained_gguf(directory,self.current_tokenizer,@@ -1738,6 +1971,19 @@ class ExportBackend:save_directory = str(resolve_export_write_dir(save_directory))logger.info(f"Saving LoRA adapter locally to: {save_directory}")save_dir_was_empty = _dir_is_fresh(save_directory)+ # One folder, one format (recursive: peft nests named adapters).+ if _IS_MLX and Path(save_directory).is_dir():+ other = _other_adapter_weight_names(resolved_format)+ if any(+ name in other for _, _, names in os.walk(save_directory) for name in names+ ):+ return (+ False,+ f"'{save_directory}' already holds the other format's adapter "+ "weights; refusing to mix MLX- and PEFT-format files in one "+ "directory. Use a different directory or remove the old adapter first.",+ None,+ )ensure_dir(Path(save_directory))if gguf:@@ -1755,8 +2001,7 @@ class ExportBackend:"\n ".join(os.path.basename(f) for f in final_ggufs) or "(none)",)elif _IS_MLX:- self.current_model.save_lora_adapters(save_directory)- self.current_tokenizer.save_pretrained(save_directory)+ self._save_mlx_adapter(save_directory, resolved_format)else:self.current_model.save_pretrained(save_directory)self.current_tokenizer.save_pretrained(save_directory)@@ -1806,8 +2051,7 @@ class ExportBackend:with tempfile.TemporaryDirectory() as tmp_dir:# Serialise first: opening the repo before this would leave an empty# one behind whenever the adapter or tokenizer fails to write.- self.current_model.save_lora_adapters(tmp_dir)- self.current_tokenizer.save_pretrained(tmp_dir)+ self._save_mlx_adapter(tmp_dir, resolved_format)repo_id = _open_hub_repo(hf_api, repo_id, private)hf_api.upload_folder(folder_path = tmp_dir,diff --git a/studio/backend/core/export/orchestrator.py b/studio/backend/core/export/orchestrator.pyindex e1742e40648..f7d5dc15ef2 100644--- a/studio/backend/core/export/orchestrator.py+++ b/studio/backend/core/export/orchestrator.py@@ -662,6 +662,7 @@ class ExportOrchestrator:private: bool = False,gguf: bool = False,gguf_outtype: str = "q8_0",+ adapter_format: Optional[str] = None,) -> Tuple[bool, str, Optional[str]]:"""Export LoRA adapter only (optionally also as a GGUF LoRA file)."""return self._run_export(@@ -674,6 +675,7 @@ class ExportOrchestrator:"private": private,"gguf": gguf,"gguf_outtype": gguf_outtype,+ "adapter_format": adapter_format,},)diff --git a/studio/backend/core/export/worker.py b/studio/backend/core/export/worker.pyindex e965370c986..b5482da9ab9 100644--- a/studio/backend/core/export/worker.py+++ b/studio/backend/core/export/worker.py@@ -468,6 +468,7 @@ def _handle_export(backend, cmd: dict, resp_queue: Any) -> None:private = cmd.get("private", False),gguf = cmd.get("gguf", False),gguf_outtype = cmd.get("gguf_outtype", "q8_0"),+ adapter_format = cmd.get("adapter_format"),)else:success, message = False, f"Unknown export type: {export_type}"diff --git a/studio/backend/models/export.py b/studio/backend/models/export.pyindex deb62ef2301..6d400f1c942 100644--- a/studio/backend/models/export.py+++ b/studio/backend/models/export.py@@ -230,6 +230,17 @@ class ExportGGUFRequest(BaseModel):class ExportLoRAAdapterRequest(ExportCommonOptions):"""Request for exporting only the LoRA adapter (not merged)."""+ adapter_format: Optional[Literal["mlx", "peft"]] = Field(+ None,+ description = "On-disk adapter format. Omitted resolves per platform "+ "(Apple-silicon MLX servers write the native MLX format, CUDA servers "+ "write the native PEFT format — omission always preserves the "+ "platform's native output), except with gguf=True, where the adapter "+ "files are always "+ "PEFT (GGUF LoRA files are built from that format). Explicit 'peft' "+ "on an MLX server converts the adapter; explicit 'mlx' on a non-MLX "+ "server — or combined with gguf=True — is an error.",+ )gguf: bool = Field(False,description = "If True, also convert the adapter to a GGUF LoRA file "diff --git a/studio/backend/models/models.py b/studio/backend/models/models.pyindex 0ad298e82b2..05513fc6ab9 100644--- a/studio/backend/models/models.py+++ b/studio/backend/models/models.py@@ -41,6 +41,13 @@ class ModelCheckpoints(BaseModel):False,description = "Whether the model uses BNB quantization (e.g. bnb-4bit)",)+ adapter_features: Optional[Dict[str, Optional[bool]]] = Field(+ None,+ description = "Compact adapter capabilities parsed from the adapter "+ "config (dora / full_state / moe_target_parameters / non_uniform); "+ "None for non-adapter runs. A None VALUE means unverified (e.g. "+ "full_state without a weight-header probe).",+ )class CheckpointListResponse(BaseModel):@@ -133,6 +140,13 @@ class LoRAInfo(BaseModel):"carries no modality otherwise, so an audio adapter reads as a text one."),)+ adapter_features: Optional[Dict[str, Optional[bool]]] = Field(+ None,+ description = "Compact adapter capabilities parsed from the adapter "+ "config (dora / full_state / moe_target_parameters / non_uniform); "+ "None when no adapter config was found. A None VALUE means "+ "unverified.",+ )class LoRAScanResponse(BaseModel):diff --git a/studio/backend/routes/export.py b/studio/backend/routes/export.pyindex 25622a9479e..306c04e9856 100644--- a/studio/backend/routes/export.py+++ b/studio/backend/routes/export.py@@ -536,6 +536,7 @@ async def export_lora_adapter(private = request.private,gguf = request.gguf,gguf_outtype = request.gguf_outtype,+ adapter_format = request.adapter_format,)if not success:diff --git a/studio/backend/routes/models.py b/studio/backend/routes/models.pyindex d44b2af12db..fb4fd26e27a 100644--- a/studio/backend/routes/models.py+++ b/studio/backend/routes/models.py@@ -2914,6 +2914,8 @@ def _disk_bytes(model_path: str, export_type: Optional[str]) -> Optional[int]:def _scan_loras_sync(resolved_outputs_dir: str, resolved_exports_dir: str, hf_token: Optional[str]) -> List[LoRAInfo]:+ from utils.models.checkpoints import parse_adapter_features+lora_list: List[LoRAInfo] = []trained_models = scan_trained_models(outputs_dir = resolved_outputs_dir)@@ -2928,6 +2930,7 @@ def _scan_loras_sync(export_type = model_type,size_bytes = _disk_bytes(model_path, model_type),audio_type = _audio_type_of_checkpoint(model_path, base_model, hf_token),+ adapter_features = parse_adapter_features(model_path),))@@ -2942,6 +2945,7 @@ def _scan_loras_sync(export_type = export_type,size_bytes = _disk_bytes(model_path, export_type),audio_type = _audio_type_of_checkpoint(model_path, base_model, hf_token),+ adapter_features = parse_adapter_features(model_path),))@@ -5589,6 +5593,7 @@ async def list_checkpoints(peft_type = metadata.get("peft_type"),lora_rank = metadata.get("lora_rank"),is_quantized = metadata.get("is_quantized", False),+ adapter_features = metadata.get("adapter_features"),)for model_name, checkpoints, metadata in raw_models]diff --git a/studio/backend/tests/test_checkpoints_scan.py b/studio/backend/tests/test_checkpoints_scan.pyindex 530dea620ee..dc19087bb84 100644--- a/studio/backend/tests/test_checkpoints_scan.py+++ b/studio/backend/tests/test_checkpoints_scan.py@@ -20,6 +20,15 @@ from utils.models import checkpoints as checkpoints_modulefrom utils.training_runs import build_default_output_dir_name+# No markers and no weight probe in a bulk listing: full_state stays unverified.+_PLAIN_FEATURES = {+ "dora": False,+ "full_state": None,+ "moe_target_parameters": False,+ "non_uniform": False,+}++def _make_history_connection(db_path: Path) -> sqlite3.Connection:conn = sqlite3.connect(str(db_path))conn.row_factory = sqlite3.Row@@ -282,7 +291,12 @@ def test_scan_checkpoints_lists_run_with_only_intermediate_checkpoints(tmp_path,("checkpoint-100", str(run_dir / "checkpoint-100"), 0.5),("checkpoint-50", str(run_dir / "checkpoint-50"), 0.75),],- {"base_model": "unsloth/X", "peft_type": "LORA", "lora_rank": 16},+ {+ "base_model": "unsloth/X",+ "peft_type": "LORA",+ "lora_rank": 16,+ "adapter_features": _PLAIN_FEATURES,+ },)]@@ -346,6 +360,11 @@ def test_scan_checkpoints_keeps_root_adapter_first(tmp_path, monkeypatch):("checkpoint-100", str(run_dir / "checkpoint-100"), 0.125),("checkpoint-50", str(run_dir / "checkpoint-50"), 0.25),],- {"base_model": "unsloth/X", "peft_type": "LORA", "lora_rank": 16},+ {+ "base_model": "unsloth/X",+ "peft_type": "LORA",+ "lora_rank": 16,+ "adapter_features": _PLAIN_FEATURES,+ },)]diff --git a/studio/backend/tests/test_export_adapter_format.py b/studio/backend/tests/test_export_adapter_format.pynew file mode 100644index 00000000000..17c918d1c9b--- /dev/null+++ b/studio/backend/tests/test_export_adapter_format.py@@ -0,0 +1,327 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""Adapter-format export: platform default, conversion routing, GGUF rejects, feature metadata."""++import json+import os+from unittest.mock import MagicMock++import pytest++from core.export import export as export_mod+from utils.models.checkpoints import parse_adapter_features+++def _backend(monkeypatch, is_mlx, tmp_path):+ monkeypatch.setattr(export_mod, "_IS_MLX", is_mlx)+ monkeypatch.setattr(export_mod, "_export_runtime_available", lambda: True)+ monkeypatch.setattr(export_mod, "resolve_export_write_dir", lambda p: tmp_path / "out")+ monkeypatch.setattr(export_mod, "ensure_dir", lambda p: os.makedirs(p, exist_ok = True))+ backend = export_mod.ExportBackend.__new__(export_mod.ExportBackend)+ backend.current_model = MagicMock()+ backend.current_tokenizer = MagicMock()+ backend.is_peft = True+ return backend+++def _peft_writer(model):+ # The real zoo converter refuses an existing destination and publishes a fresh one.+ def _save(+ path,+ adapter_config = None,+ adapter_format = "mlx",+ ):+ assert not os.path.lexists(path)+ os.makedirs(path)+ with open(os.path.join(path, "adapter_model.safetensors"), "w") as f:+ f.write(adapter_format)+ with open(os.path.join(path, "adapter_config.json"), "w") as f:+ json.dump({"r": 8}, f)++ model.save_lora_adapters = MagicMock(side_effect = _save)+++ "is_mlx,requested,expect",+ [+ (True, None, "mlx"),+ (True, "mlx", "mlx"),+ (True, "peft", "peft"),+ (False, None, "peft"),+ (False, "peft", "peft"),+ (False, "mlx", "error"),+ ],+)+def test_six_cell_matrix(monkeypatch, tmp_path, is_mlx, requested, expect):+ backend = _backend(monkeypatch, is_mlx, tmp_path)+ if expect == "peft" and is_mlx:+ _peft_writer(backend.current_model)+ ok, message, _path = backend.export_lora_adapter(+ str(tmp_path / "dst"),+ adapter_format = requested,+ )+ if expect == "error":+ assert not ok and "MLX" in message+ backend.current_model.save_pretrained.assert_not_called()+ return+ assert ok, message+ if is_mlx:+ args, kwargs = backend.current_model.save_lora_adapters.call_args+ backend.current_model.save_pretrained.assert_not_called()+ if expect == "mlx":+ assert args == (str(tmp_path / "out"),) and kwargs == {}+ else:+ assert kwargs == {"adapter_format": "peft"}+ assert (tmp_path / "out" / "adapter_model.safetensors").read_text() == "peft"+ else:+ backend.current_model.save_pretrained.assert_called_once()+ backend.current_model.save_lora_adapters.assert_not_called()+++def test_repeat_peft_export_overwrites(monkeypatch, tmp_path):+ backend = _backend(monkeypatch, True, tmp_path)+ _peft_writer(backend.current_model)+ out = tmp_path / "out"+ out.mkdir()+ (out / "adapter_model.safetensors").write_text("stale")+ for _ in range(2):+ ok, message, _ = backend.export_lora_adapter(str(out), adapter_format = "peft")+ assert ok, message+ assert (out / "adapter_model.safetensors").read_text() == "peft"+ assert sorted(p.name for p in tmp_path.iterdir()) == ["out"]+++def test_cuda_hub_push_unchanged(monkeypatch, tmp_path):+ backend = _backend(monkeypatch, False, tmp_path)+ monkeypatch.setattr(export_mod, "HfApi", lambda token = None: MagicMock())+ monkeypatch.setattr(export_mod, "_open_hub_repo", lambda hf_api, repo_id, private: repo_id)+ monkeypatch.setattr(export_mod, "_publish_unsloth_model_card", lambda *a: None)+ ok, message, _ = backend.export_lora_adapter("", push_to_hub = True, repo_id = "u/r", hf_token = "t")+ assert ok, message+ backend.current_model.push_to_hub.assert_called_once_with("u/r", token = "t", private = False)+++def test_outdated_zoo_hard_error(monkeypatch, tmp_path):+ backend = _backend(monkeypatch, True, tmp_path)++ def _old_zoo_saver(path, adapter_config = None): # no adapter_format kwarg+ raise AssertionError("an outdated saver must not be invoked")++ backend.current_model.save_lora_adapters = _old_zoo_saver+ ok, message, _ = backend.export_lora_adapter(+ str(tmp_path / "dst"),+ adapter_format = "peft",+ )+ assert not ok and "unsloth-zoo" in message++ def _modern_saver_with_internal_bug(+ path,+ adapter_config = None,+ adapter_format = "mlx",+ ):+ raise TypeError("scale must be a float")++ backend.current_model.save_lora_adapters = _modern_saver_with_internal_bug+ ok, message, _ = backend.export_lora_adapter(+ str(tmp_path / "dst2"),+ adapter_format = "peft",+ )+ assert not ok and "unsloth-zoo" not in message and "scale" in message+++ "cfg,fs_attr,reason",+ [+ ({"alpha_pattern": {"^q_proj": 32}}, None, "alpha"),+ ({"use_rslora": True, "rank_pattern": {"^q_proj": 4}}, None, "rsLoRA"),+ ({"use_dora": True}, None, "DoRA"),+ ({"modules_to_save": ["lm_head"]}, None, "full-module state"),+ ({}, {"model.embed_tokens": "embedding_auto"}, "full-module state"),+ ({"target_parameters": ["experts.gate_up_proj"]}, None, "expert"),+ ],+)+def test_gguf_rejects(monkeypatch, tmp_path, cfg, fs_attr, reason):+ backend = _backend(monkeypatch, True, tmp_path)+ backend.current_model._unsloth_full_state_modules = fs_attr+ (tmp_path / "adapter_config.json").write_text(json.dumps(cfg))+ with pytest.raises(RuntimeError, match = reason):+ backend._convert_peft_dir_to_gguf(str(tmp_path), "q8_0", None)+++def _converter_harness(monkeypatch, tmp_path, with_converter):+ import importlib.util+ import subprocess+ import sys+ import types++ llama = tmp_path / "home" / "llama.cpp"+ llama.mkdir(parents = True)+ if with_converter:+ (llama / "gguf-py").mkdir()+ (llama / "convert_lora_to_gguf.py").write_text("")+ zoo = types.ModuleType("unsloth_zoo")+ zoo.llama_cpp = types.SimpleNamespace(+ LLAMA_CPP_DEFAULT_DIR = str(llama),+ _resolve_converter_revision = lambda d: ("ggml-org/llama.cpp", "b9000-mix-abc"),+ )+ monkeypatch.setitem(sys.modules, "unsloth_zoo", zoo)+ monkeypatch.setitem(sys.modules, "unsloth_zoo.llama_cpp", zoo.llama_cpp)+ calls = []++ def _run(+ cmd,+ env = None,+ **kwargs,+ ):+ calls.append((cmd, env))+ if cmd[:2] == ["git", "clone"]:+ os.makedirs(os.path.join(cmd[-1], "gguf-py"))+ open(os.path.join(cmd[-1], "convert_lora_to_gguf.py"), "w").close()+ return types.SimpleNamespace(returncode = 0, stdout = "", stderr = "")++ monkeypatch.setattr(subprocess, "run", _run)+ real_find_spec = importlib.util.find_spec+ monkeypatch.setattr(+ importlib.util,+ "find_spec",+ lambda name, *a: object() if name == "torch" else real_find_spec(name, *a),+ )+ backend = _backend(monkeypatch, True, tmp_path)+ backend.current_model._unsloth_full_state_modules = None+ adapter = tmp_path / "adapter"+ adapter.mkdir()+ (adapter / "adapter_config.json").write_text(json.dumps({"base_model_name_or_path": "o/m"}))+ return backend, str(adapter), calls++[email protected]("token,expect", [(False, None), ("hf_x", "hf_x")])+def test_gguf_converter_token_env(monkeypatch, tmp_path, token, expect):+ monkeypatch.setenv("HF_TOKEN", "host-token")+ backend, adapter, calls = _converter_harness(monkeypatch, tmp_path, True)+ backend._convert_peft_dir_to_gguf(adapter, "q8_0", token)+ env = calls[-1][1]+ assert env.get("HF_TOKEN") == expect+ assert env.get("HF_HUB_DISABLE_IMPLICIT_TOKEN") == ("1" if token is False else "0")+++def test_gguf_converter_cloned_without_package_manager(monkeypatch, tmp_path):+ backend, adapter, calls = _converter_harness(monkeypatch, tmp_path, False)+ backend._convert_peft_dir_to_gguf(adapter, "q8_0", None)+ assert calls[0][0][:6] == ["git", "clone", "--depth", "1", "--branch", "b9000"]+ source = tmp_path / "home" / "llama.cpp-source-b9000"+ assert calls[-1][0][1] == str(source / "convert_lora_to_gguf.py")+ assert sorted(p.name for p in (tmp_path / "home").iterdir()) == [+ "llama.cpp",+ "llama.cpp-source-b9000",+ ]+++def test_parse_adapter_features(tmp_path):+ def _dir(cfg):+ d = tmp_path / f"a{len(list(tmp_path.iterdir()))}"+ d.mkdir()+ (d / "adapter_config.json").write_text(json.dumps(cfg))+ return str(d)++ assert parse_adapter_features(str(tmp_path)) is None # no config+ base = parse_adapter_features(_dir({"r": 8}))+ assert base == {+ "dora": False,+ "full_state": None,+ "moe_target_parameters": False,+ "non_uniform": False,+ }+ assert parse_adapter_features(_dir({"fine_tune_type": "lora"}))["full_state"] is None+ np = pytest.importorskip("numpy")+ save_file = pytest.importorskip("safetensors.numpy").save_file++ d_mlx = _dir({"fine_tune_type": "lora"})+ save_file(+ {"model.layers.0.self_attn.q_proj.lora_a": np.zeros((2, 2), dtype = "float32")},+ os.path.join(d_mlx, "adapters.safetensors"),+ )+ assert parse_adapter_features(d_mlx)["full_state"] is False+ save_file(+ {+ "model.layers.0.self_attn.q_proj.lora_a": np.zeros((2, 2), dtype = "float32"),+ "lm_head.bias": np.zeros((2,), dtype = "float32"),+ },+ os.path.join(d_mlx, "adapters.safetensors"),+ )+ assert parse_adapter_features(d_mlx)["full_state"] is True+ assert parse_adapter_features(_dir({"use_dora": True}))["dora"] is True+ assert parse_adapter_features(_dir({"fine_tune_type": "dora"}))["dora"] is True+ assert parse_adapter_features(_dir({"modules_to_save": ["lm_head"]}))["full_state"] is True+ assert (+ parse_adapter_features(_dir({"full_state_modules": {"lm_head": "modules_to_save"}}))[+ "full_state"+ ]+ is True+ )+ assert (+ parse_adapter_features(_dir({"target_parameters": ["experts.g"]}))["moe_target_parameters"]+ is True+ )+ assert parse_adapter_features(_dir({"rank_pattern": {"q": 4}}))["non_uniform"] is True+ assert (+ parse_adapter_features(_dir({"unsloth_mlx_lora_module_scales": {"q": 2.0}}))["non_uniform"]+ is True+ )+++def test_local_dir_never_format_mixed(monkeypatch, tmp_path):+ backend = _backend(monkeypatch, True, tmp_path)+ out = tmp_path / "out"+ out.mkdir()+ (out / "adapter_model.safetensors").write_bytes(b"x") # other format+ ok, message, _ = backend.export_lora_adapter(str(out))+ assert not ok and "mix" in message+ backend.current_model.save_lora_adapters.assert_not_called()+ (out / "adapter_model.safetensors").unlink()+ (out / "named").mkdir()+ (out / "named" / "adapter_model.safetensors").write_bytes(b"x")+ ok, message, _ = backend.export_lora_adapter(str(out))+ assert not ok and "mix" in message+ (out / "named" / "adapter_model.safetensors").unlink()+ (out / "adapter_model.bin").write_bytes(b"x")+ ok, message, _ = backend.export_lora_adapter(str(out))+ assert not ok and "mix" in message+++def test_gguf_converter_offline_refuses_clone(monkeypatch, tmp_path):+ import sys++ backend, adapter, calls = _converter_harness(monkeypatch, tmp_path, False)+ sys.modules["unsloth_zoo.llama_cpp"]._converter_network_allowed = lambda: False+ with pytest.raises(RuntimeError, match = "offline"):+ backend._convert_peft_dir_to_gguf(adapter, "q8_0", None)+ assert calls == []+++def test_gguf_converter_honors_scripts_dir(monkeypatch, tmp_path):+ import sys++ backend, adapter, calls = _converter_harness(monkeypatch, tmp_path, False)+ pinned = tmp_path / "pinned"+ pinned.mkdir()+ monkeypatch.setenv("UNSLOTH_LLAMA_CPP_SCRIPTS_DIR", str(pinned))+ sys.modules["unsloth_zoo.llama_cpp"]._resolve_converter_revision = None # must not be called+ with pytest.raises(RuntimeError, match = "UNSLOTH_LLAMA_CPP_SCRIPTS_DIR"):+ backend._convert_peft_dir_to_gguf(adapter, "q8_0", None)+ (pinned / "convert_lora_to_gguf.py").write_text("")+ (pinned / "gguf-py").mkdir()+ backend._convert_peft_dir_to_gguf(adapter, "q8_0", None)+ assert [c[0][1] for c in calls] == [str(pinned / "convert_lora_to_gguf.py")]+++def test_gguf_converter_uses_loaded_snapshot(monkeypatch, tmp_path):+ backend, adapter, calls = _converter_harness(monkeypatch, tmp_path, True)+ snap = tmp_path / "snapshot"+ snap.mkdir()+ (snap / "config.json").write_text("{}")+ backend.current_model._config_src_path = None+ backend.current_model._src_path = str(snap)+ backend._convert_peft_dir_to_gguf(adapter, "q8_0", None)+ cmd = calls[-1][0]+ assert cmd[cmd.index("--base") + 1] == str(snap) and "--base-model-id" not in cmddiff --git a/studio/backend/utils/models/checkpoints.py b/studio/backend/utils/models/checkpoints.pyindex 94184122515..2294c2e2174 100644--- a/studio/backend/utils/models/checkpoints.py+++ b/studio/backend/utils/models/checkpoints.py@@ -6,11 +6,12 @@from __future__ import annotationsimport json+import osimport reimport structlogfrom loggers import get_loggerfrom pathlib import Path-from typing import List, Optional, Tuple+from typing import Dict, List, Optional, Tuplefrom hub.utils.hf_tokens import HfTokenArgfrom storage.studio_db import get_connectionfrom utils.training_runs import (@@ -143,6 +144,65 @@ def _read_checkpoint_loss(checkpoint_path: Path) -> Optional[float]:return None+def parse_adapter_features(+ adapter_path: str, probe_weights: bool = True+) -> Optional[Dict[str, Optional[bool]]]:+ """Adapter feature flags (PEFT or MLX config) for the export UI; None without a config.++ ``full_state`` is tri-state: no config marker proves absence (PEFT saves embedding state only+ as weight keys), so a negative needs the weight-header probe and stays None without it.+ """+ cfg_path = os.path.join(adapter_path, "adapter_config.json")+ try:+ with open(cfg_path, "r", encoding = "utf-8") as f:+ cfg = json.load(f)+ except (OSError, ValueError):+ return None+ if not isinstance(cfg, dict):+ return None++ def _flag(value):+ return isinstance(value, bool) and value++ def _filled(value):+ return isinstance(value, (dict, list)) and len(value) > 0++ full_state: Optional[bool] = _filled(cfg.get("full_state_modules")) or _filled(+ cfg.get("modules_to_save")+ )+ if not full_state:+ full_state = None+ if probe_weights:+ for weights, is_adapter_key in (+ (+ os.path.join(adapter_path, "adapter_model.safetensors"),+ lambda key: ".lora_" in key,+ ),+ (+ os.path.join(adapter_path, "adapters.safetensors"),+ lambda key: key.endswith((".lora_a", ".lora_b", ".m")),+ ),+ ):+ if not os.path.exists(weights):+ continue+ try:+ from safetensors import safe_open+ with safe_open(weights, framework = "numpy") as f:+ full_state = any(not is_adapter_key(key) for key in f.keys())+ except Exception:+ full_state = None+ break+ return {+ "dora": _flag(cfg.get("use_dora")) or str(cfg.get("fine_tune_type", "")).lower() == "dora",+ "full_state": full_state,+ "moe_target_parameters": _filled(cfg.get("target_parameters")),+ "non_uniform": _filled(cfg.get("rank_pattern"))+ or _filled(cfg.get("alpha_pattern"))+ or _filled(cfg.get("unsloth_mlx_lora_module_ranks"))+ or _filled(cfg.get("unsloth_mlx_lora_module_scales")),+ }++# Both probe every outputs folder, so an unreadable one is skipped, not fatal to the scan.def _has_own_model(path: Path) -> bool:try:@@ -215,6 +275,9 @@ def scan_checkpoints(metadata["base_model"] = cfg.get("base_model_name_or_path")metadata["peft_type"] = cfg.get("peft_type")metadata["lora_rank"] = cfg.get("r")+ metadata["adapter_features"] = parse_adapter_features(+ str(meta_dir), probe_weights = False+ )elif own_entry(config_file):cfg = json.loads(config_file.read_text(encoding = "utf-8-sig"))metadata["base_model"] = cfg.get("_name_or_path")diff --git a/studio/frontend/src/features/export/api/export-api.ts b/studio/frontend/src/features/export/api/export-api.tsindex 9763b0d6729..7cd75c99bf7 100644--- a/studio/frontend/src/features/export/api/export-api.ts+++ b/studio/frontend/src/features/export/api/export-api.ts@@ -59,6 +59,12 @@ export interface ModelCheckpoints {peft_type?: string | null;lora_rank?: number | null;is_quantized?: boolean;+ adapter_features?: {+ dora?: boolean | null;+ full_state?: boolean | null;+ moe_target_parameters?: boolean | null;+ non_uniform?: boolean | null;+ } | null;}export interface CheckpointListResponse {@@ -188,6 +194,8 @@ export async function exportLoRA(params: {gguf?: boolean;/** GGUF LoRA output float type (f32/f16/bf16/q8_0/auto); only used when gguf=true. */gguf_outtype?: string;+ /** On-disk adapter format; omitted resolves to the platform's native format. */+ adapter_format?: "mlx" | "peft";}): Promise<ExportOperationResponse> {const response = await authFetch("/api/export/export/lora", {method: "POST",diff --git a/studio/frontend/src/features/export/constants.ts b/studio/frontend/src/features/export/constants.tsindex be9080ba14f..a97b82d49ae 100644--- a/studio/frontend/src/features/export/constants.ts+++ b/studio/frontend/src/features/export/constants.ts@@ -343,3 +343,62 @@ export const GUIDE_STEPS = ["Click Export and choose your destination","Test your model and compare outputs in Chat",];+++/** A null value means unverified (e.g. full_state without a weight probe). */+export interface AdapterFeatures {+ dora?: boolean | null;+ full_state?: boolean | null;+ moe_target_parameters?: boolean | null;+ non_uniform?: boolean | null;+}++export type AdapterFormat = "mlx" | "peft";++/** The vLLM claim needs VERIFIED plain LoRA: vLLM rejects DoRA / modules_to_save and ignores per-module rank/alpha. */+export function adapterCompatibilityTip(+ format: AdapterFormat,+ features: AdapterFeatures | null | undefined,+): string {+ if (format === "mlx") {+ const base =+ "MLX (default): the native format for mlx-lm and Apple-silicon " ++ "workflows — the format training checkpoints are saved in.";+ return features?.non_uniform+ ? base ++ " Adapters with per-module ranks/alphas exported as MLX require " ++ "Unsloth to load them; stock mlx-lm supports uniform adapters " ++ "only — choose PEFT for maximum compatibility."+ : base;+ }+ const base = "PEFT: the standard Hugging Face adapter format — ";+ if (features == null) {+ return base + "loads in transformers and PEFT.";+ }+ if (features.dora || features.full_state) {+ return base + "loads in transformers/PEFT; not supported by vLLM.";+ }+ if (features.moe_target_parameters) {+ return base + "vLLM support varies and is not guaranteed.";+ }+ if (features.non_uniform) {+ return (+ base ++ "loads in transformers and PEFT. vLLM applies a single global " ++ "rank/alpha — per-module patterned adapters are not supported by vLLM."+ );+ }+ const verifiedPlain =+ features.dora === false &&+ features.full_state === false &&+ features.moe_target_parameters === false &&+ features.non_uniform === false;+ if (!verifiedPlain) {+ return base + "loads in transformers and PEFT.";+ }+ return (+ base ++ "loads in transformers, vLLM, and Unsloth Studio on GPU machines, and " ++ "is required for GGUF adapter export."+ );+}diff --git a/studio/frontend/src/features/export/export-page.tsx b/studio/frontend/src/features/export/export-page.tsxindex 96881ec8a4a..858f571e4ee 100644--- a/studio/frontend/src/features/export/export-page.tsx+++ b/studio/frontend/src/features/export/export-page.tsx@@ -64,6 +64,7 @@ import { useSearch } from "@tanstack/react-router";import { useCallback, useEffect, useMemo, useRef, useState } from "react";import { useShallow } from "zustand/react/shallow";import type { ModelCheckpoints } from "./api/export-api";+import { adapterCompatibilityTip, type AdapterFormat } from "./constants";import { ExportRunPanel } from "./components/export-run-panel";import { MethodPicker } from "./components/method-picker";import { QuantPicker } from "./components/quant-picker";@@ -225,12 +226,13 @@ export function ExportPage() {});// LoRA-only export: optionally also emit a GGUF LoRA adapter, and its output float type.const [loraAsGguf, setLoraAsGguf] = useState(false);+ const [adapterFormat, setAdapterFormat] = useState<AdapterFormat>("mlx");const [loraGgufOuttype, setLoraGgufOuttype] = useState<string>("q8_0");// GGUF method: export the full model as GGUF quants, or (for an adapter checkpoint) a GGUF LoRA.const [ggufTarget, setGgufTarget] = useState<"model" | "lora">("model");const hardware = useHardwareInfo();- // GGUF LoRA conversion is rejected on the macOS / MLX path, so gate it out on a Mac host.+ // On Mac, GGUF LoRA adapters ship through the LoRA method's toggle, not the GGUF method.const isMacHost = usePlatformStore((s) => s.deviceType) === "mac";const torchaoUnavailable = !hardware.torchaoExportSupported;// Real CUDA (not ROCm); gates the NVIDIA-only compressed-tensors formats.@@ -623,11 +625,22 @@ export function ExportPage() {return siblingGgufDirectory(localModel.path) ?? relative;}}+ // Mac PEFT / GGUF adapters get their own folder: one folder holds one adapter format.+ if (+ isMacHost &&+ exportMethod === "lora" &&+ (loraAsGguf || adapterFormat === "peft")+ ) {+ return `${relative}-peft`;+ }return relative;}, [+ adapterFormat,checkpoint,exportMethod,+ isMacHost,localMetaById,+ loraAsGguf,modelSource,selectedModelIdx,selectedSourceModel,@@ -757,8 +770,7 @@ export function ExportPage() {const token = pushToHub && actionHfToken ? actionHfToken : undefined;// The GGUF method with the LoRA target reuses the LoRA-adapter export path.const effectiveMethod: ExportMethod = ggufAsLora ? "lora" : exportMethod;- const emitLoraGguf =- ggufAsLora || (effectiveMethod === "lora" && loraAsGguf && !isMacHost);+ const emitLoraGguf = ggufAsLora || (effectiveMethod === "lora" && loraAsGguf);const methodLabel = ggufAsLora? "GGUF LoRA adapter": (EXPORT_METHODS.find((m) => m.value === exportMethod)?.title ??@@ -803,6 +815,7 @@ export function ExportPage() {})),loraGguf: emitLoraGguf,loraGgufOuttype,+ adapterFormat: isMacHost && !emitLoraGguf ? adapterFormat : undefined,saveDirectory,destination,repoId,@@ -838,6 +851,7 @@ export function ExportPage() {loraAsGguf,isMacHost,loraGgufOuttype,+ adapterFormat,exportUnsupported,destination,saveDirectory,@@ -1563,7 +1577,7 @@ export function ExportPage() {variant={loraAsGguf ? "outline" : "default"}size="sm"onClick={() => setLoraAsGguf(false)}- title="Standard PEFT adapter (adapter_model.safetensors)."+ title="Adapter weights as safetensors.">Adapter (safetensors)</Button>@@ -1571,26 +1585,66 @@ export function ExportPage() {type="button"variant={loraAsGguf ? "default" : "outline"}size="sm"- disabled={isMacHost}onClick={() => setLoraAsGguf(true)}- title={- isMacHost- ? "GGUF LoRA export is not available on macOS/MLX. Use the safetensors adapter."- : "llama.cpp GGUF LoRA, loadable with `llama-cli --lora`."- }+ title="llama.cpp GGUF LoRA, loadable with `llama-cli --lora`.">GGUF adapter</Button></div><div className="text-xs text-muted-foreground">- {isMacHost- ? "GGUF LoRA is not available on macOS/MLX; exporting the safetensors adapter."- : loraAsGguf- ? "Converts the adapter to a GGUF LoRA (llama.cpp `--lora`). The base model stays separate."+ {loraAsGguf+ ? isMacHost+ ? "Converts the adapter to a GGUF LoRA (llama.cpp `--lora`); the adapter files are written in PEFT format. Not available for adapters with per-module alpha values, rsLoRA with per-module ranks, DoRA, replaced embeddings or modules_to_save, or expert-parameter targets."+ : "Converts the adapter to a GGUF LoRA (llama.cpp `--lora`). The base model stays separate."+ : isMacHost+ ? "Adapter weights only; pick the on-disk format below.": "Standard PEFT adapter files. Pair with the base model at inference."}</div></div>+ {!loraAsGguf && isMacHost && (+ <div+ className="space-y-2"+ data-testid="adapter-format-picker"+ >+ <div className="text-sm font-medium">+ Safetensors format+ </div>+ <div className="flex flex-wrap gap-2">+ <Button+ type="button"+ variant={+ adapterFormat === "mlx" ? "default" : "outline"+ }+ size="sm"+ onClick={() => setAdapterFormat("mlx")}+ title="Native mlx-lm adapter (adapters.safetensors)."+ >+ MLX+ </Button>+ <Button+ type="button"+ variant={+ adapterFormat === "peft" ? "default" : "outline"+ }+ size="sm"+ onClick={() => setAdapterFormat("peft")}+ title="Standard Hugging Face PEFT adapter (adapter_model.safetensors)."+ >+ PEFT+ </Button>+ </div>+ <div className="text-xs text-muted-foreground">+ {adapterCompatibilityTip(+ adapterFormat,+ selectedModelData?.adapter_features,+ )}{" "}+ Training checkpoints always remain MLX; this choice+ only affects the exported copy.+ </div>+ </div>+ )}+{loraAsGguf && (<div className="space-y-1.5"><div className="text-sm font-medium">Output type</div>diff --git a/studio/frontend/src/features/export/stores/export-runtime-store.ts b/studio/frontend/src/features/export/stores/export-runtime-store.tsindex 62774d11f7c..c26958ef77c 100644--- a/studio/frontend/src/features/export/stores/export-runtime-store.ts+++ b/studio/frontend/src/features/export/stores/export-runtime-store.ts@@ -151,6 +151,7 @@ export interface RunExportParams {}[];/** LoRA: also emit a GGUF LoRA adapter (llama.cpp `--lora`), and its output float type. */loraGguf?: boolean;+ adapterFormat?: "mlx" | "peft";loraGgufOuttype?: string;saveDirectory: string;destination: ExportDestination;@@ -516,6 +517,7 @@ export const useExportRuntimeStore = create<ExportRuntimeStore>()((set, get) =>private: params.privateRepo,gguf: params.loraGguf ?? false,gguf_outtype: params.loraGgufOuttype ?? "q8_0",+ adapter_format: params.adapterFormat,}),);if (outputPath) {diff --git a/unsloth_cli/commands/export.py b/unsloth_cli/commands/export.pyindex c72c0a81814..5a69ced329e 100644--- a/unsloth_cli/commands/export.py+++ b/unsloth_cli/commands/export.py@@ -1,6 +1,7 @@# SPDX-License-Identifier: AGPL-3.0-only# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0+import platformfrom pathlib import Pathfrom typing import Optional@@ -10,6 +11,13 @@ from unsloth_cli._studio_deps import studio_backend_importsEXPORT_FORMATS = ["merged-16bit", "merged-4bit", "gguf", "lora"]+ADAPTER_FORMATS = ["mlx", "peft"]+++def _is_apple_silicon() -> bool:+ return platform.system() == "Darwin" and platform.machine() == "arm64"++GGUF_QUANTS = ["q4_k_m", "q5_k_m", "q8_0", "f16"]@@ -70,6 +78,14 @@ def export(help = "Load the checkpoint in 4-bit. Default: 16-bit for an unquantized full model ""(except with merged-4bit), 4-bit otherwise.",),+ adapter_format: Optional[str] = typer.Option(+ None,+ "--adapter-format",+ help = "LoRA adapter on-disk format (mlx or peft); omitted writes the "+ "platform's native format. Apple-silicon hosts only.",+ # Registered everywhere so off-Mac use gets a clear error.+ hidden = not _is_apple_silicon(),+ ),):"""Export a checkpoint to various formats (merged, GGUF, LoRA adapter)."""if format not in EXPORT_FORMATS:@@ -83,6 +99,28 @@ def export(typer.echo("Error: --repo-id required when using --push-to-hub", err = True)raise typer.Exit(code = 2)+ if adapter_format is not None:+ if adapter_format not in ADAPTER_FORMATS:+ typer.echo(+ f"Error: Invalid adapter format '{adapter_format}'. "+ f"Choose from: {', '.join(ADAPTER_FORMATS)}",+ err = True,+ )+ raise typer.Exit(code = 2)+ if format != "lora":+ typer.echo(+ "Error: --adapter-format only applies to --format lora",+ err = True,+ )+ raise typer.Exit(code = 2)+ if not _is_apple_silicon():+ typer.echo(+ "Error: --adapter-format is only available on Apple-silicon "+ "hosts; this platform exports the native PEFT format.",+ err = True,+ )+ raise typer.Exit(code = 2)+# A full model is saved as loaded, so merged-4bit still needs the 4-bit load.if load_in_4bit is None and format == "merged-4bit":load_in_4bit = True@@ -140,6 +178,7 @@ def export(repo_id = repo_id,hf_token = hf_token,private = private,+ adapter_format = adapter_format,)if not success:diff --git a/unsloth_cli/tests/test_export_adapter_format_flag.py b/unsloth_cli/tests/test_export_adapter_format_flag.pynew file mode 100644index 00000000000..d9566b46412--- /dev/null+++ b/unsloth_cli/tests/test_export_adapter_format_flag.py@@ -0,0 +1,55 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""Mac pass-through and off-Mac rejection for --adapter-format."""++import sys+import types+from pathlib import Path++import typer+from typer.testing import CliRunner++_REPO_ROOT = Path(__file__).resolve().parents[2]+if str(_REPO_ROOT) not in sys.path:+ sys.path.insert(0, str(_REPO_ROOT))+++class _FakeBackend:+ def __init__(self, lora_result = (True, "exported", "/tmp/out")):+ self.lora_result, self.lora_kwargs = lora_result, None++ def load_checkpoint(self, **kwargs):+ return True, "loaded"++ def export_lora_adapter(self, **kwargs):+ self.lora_kwargs = kwargs+ return self.lora_result+++def _run(+ monkeypatch,+ args,+ is_mac,+ backend = None,+):+ from unsloth_cli.commands import export as export_mod++ backend = backend or _FakeBackend()+ monkeypatch.setattr(export_mod, "_is_apple_silicon", lambda: is_mac)+ fake_core = types.SimpleNamespace(ExportBackend = lambda: backend)+ monkeypatch.setitem(sys.modules, "studio.backend.core.export", fake_core)+ app = typer.Typer()+ app.command()(export_mod.export)+ result = CliRunner().invoke(app, ["/tmp/ckpt", "/tmp/out", "--format", "lora", *args])+ return result, backend+++def test_flag_contract(monkeypatch):+ result, backend = _run(monkeypatch, ["--adapter-format", "peft"], is_mac = True)+ assert result.exit_code == 0, result.output+ assert backend.lora_kwargs["adapter_format"] == "peft"+ result, backend = _run(monkeypatch, ["--adapter-format", "mlx"], is_mac = False)+ assert (+ result.exit_code == 2 and "Apple-silicon" in result.stderr and backend.lora_kwargs is None+ )