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.

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.py
index 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_exc
from 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_token
from utils.hardware import clear_gpu_cache
from 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 = model
self.current_tokenizer = tokenizer
self.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)
+ return
self.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.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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.py
index 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_module
from 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.py
new file mode 100644
index 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 cmd
diff --git a/studio/backend/utils/models/checkpoints.py b/studio/backend/utils/models/checkpoints.py
index 94184122515..2294c2e2174 100644
--- a/studio/backend/utils/models/checkpoints.py
+++ b/studio/backend/utils/models/checkpoints.py
@@ -6,11 +6,12 @@
from __future__ import annotations
import json
+import os
import re
import structlog
from loggers import get_logger
from pathlib import Path
-from typing import List, Optional, Tuple
+from typing import Dict, List, Optional, Tuple
from hub.utils.hf_tokens import HfTokenArg
from storage.studio_db import get_connection
from 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.ts
index 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.ts
index 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.tsx
index 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.ts
index 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.py
index 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 platform
from pathlib import Path
from typing import Optional
@@ -10,6 +11,13 @@ from unsloth_cli._studio_deps import studio_backend_imports
EXPORT_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.py
new file mode 100644
index 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
+ )