Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: consent dialog before FP8/FP4 llm-compressor install (Phase 2) (#9554)

Sourav Rajvicc41f5e2c57a
diff --git a/studio/backend/core/export/export.py b/studio/backend/core/export/export.py
index 7de246d0609..0c30fce50e5 100644
--- a/studio/backend/core/export/export.py
+++ b/studio/backend/core/export/export.py
@@ -1005,6 +1005,7 @@ class ExportBackend:
hf_token: HfTokenArg = None,
private: bool = False,
compressed_method: Optional[str] = None,
+ install_missing_dependencies: bool = False,
) -> Tuple[bool, str, Optional[str]]:
"""Export a merged model (a no-op merge for non-PEFT base models).
@@ -1085,14 +1086,27 @@ class ExportBackend:
# Prefer the llm-compressor-main shadow (transformers 5.x): the shipped 0.10.x cannot quantize newer
# models.
_shadow_pp = None
+ _shadow_offered = False
try:
- from utils.transformers_version import llmcompressor_shadow_pythonpath
- _shadow_pp = llmcompressor_shadow_pythonpath()
+ from utils.transformers_version import (
+ _env_offline,
+ _llmcompressor_main_disabled,
+ llmcompressor_shadow_pythonpath,
+ )
+
+ # Same rule as the consent probe: the dialog names the shadow whenever it can be provisioned.
+ _shadow_offered = not _llmcompressor_main_disabled() and not _env_offline()
+ _shadow_pp = llmcompressor_shadow_pythonpath(
+ allow_provision = install_missing_dependencies,
+ )
except Exception as e:
logger.warning(f"llm-compressor-main shadow unavailable: {e}")
if _shadow_pp:
os.environ[_us._COMPRESSED_QUANTIZE_PYTHONPATH_ENV] = _shadow_pp
else:
+ # Consent for the shadow does not cover installing into this interpreter instead.
+ if _shadow_offered:
+ install_missing_dependencies = False
# The workspace 0.10.x cannot exceed its transformers ceiling, so fail fast for sidecar models.
os.environ.pop(_us._COMPRESSED_QUANTIZE_PYTHONPATH_ENV, None)
_exceeds, _tf_ver = _us._transformers_exceeds_llm_compressor_ceiling()
@@ -1102,8 +1116,9 @@ class ExportBackend:
"FP8/FP4 compressed-tensors export is not available for this model: it "
f"runs under transformers {_tf_ver}, but the installed llm-compressor "
f"supports transformers <= {_us._LLM_COMPRESSOR_MAX_TRANSFORMERS} and the "
- "llm-compressor-main runtime could not be provisioned (offline or "
- "UNSLOTH_DISABLE_LLMCOMPRESSOR_MAIN). Export to GGUF or 16-bit instead.",
+ "llm-compressor-main runtime is not set up (install not approved, "
+ "offline, UNSLOTH_DISABLE_LLMCOMPRESSOR_MAIN, or provisioning failed). "
+ "Approve the install, or export to GGUF or 16-bit instead.",
None,
)
@@ -1144,6 +1159,14 @@ class ExportBackend:
and _supports_kwarg(self.current_model.save_pretrained_merged, "token")
else {}
)
+ # Always explicit: the library defaults to auto-installing, so an unconsented export must say False.
+ consent_kw = (
+ {"install_missing_dependencies": bool(install_missing_dependencies)}
+ if _supports_kwarg(
+ self.current_model.save_pretrained_merged, "install_missing_dependencies"
+ )
+ else {}
+ )
if _IS_MLX:
self.current_model.save_pretrained_merged(
save_directory,
@@ -1156,6 +1179,7 @@ class ExportBackend:
save_directory,
self.current_tokenizer,
save_method = save_method,
+ **consent_kw,
**merged_token_kw,
)
@@ -1255,6 +1279,14 @@ class ExportBackend:
save_method = save_method,
token = hf_token,
private = private,
+ **(
+ {"install_missing_dependencies": bool(install_missing_dependencies)}
+ if _supports_kwarg(
+ self.current_model.push_to_hub_merged,
+ "install_missing_dependencies",
+ )
+ else {}
+ ),
)
logger.info(f"Model pushed successfully to {repo_id}")
diff --git a/studio/backend/core/export/orchestrator.py b/studio/backend/core/export/orchestrator.py
index c712f47f8d8..6e295db8a3f 100644
--- a/studio/backend/core/export/orchestrator.py
+++ b/studio/backend/core/export/orchestrator.py
@@ -600,6 +600,7 @@ class ExportOrchestrator:
hf_token: HfTokenArg = None,
private: bool = False,
compressed_method: Optional[str] = None,
+ install_missing_dependencies: bool = False,
) -> Tuple[bool, str, Optional[str]]:
return self._run_export(
"merged",
@@ -611,6 +612,7 @@ class ExportOrchestrator:
"hf_token": hf_token,
"private": private,
"compressed_method": compressed_method,
+ "install_missing_dependencies": install_missing_dependencies,
},
)
diff --git a/studio/backend/core/export/worker.py b/studio/backend/core/export/worker.py
index b5482da9ab9..a76c60cb0e8 100644
--- a/studio/backend/core/export/worker.py
+++ b/studio/backend/core/export/worker.py
@@ -439,6 +439,7 @@ def _handle_export(backend, cmd: dict, resp_queue: Any) -> None:
hf_token = cmd.get("hf_token"),
private = cmd.get("private", False),
compressed_method = cmd.get("compressed_method"),
+ install_missing_dependencies = cmd.get("install_missing_dependencies", False),
)
elif export_type == "base":
success, message, output_path = backend.export_base_model(
diff --git a/studio/backend/models/__init__.py b/studio/backend/models/__init__.py
index e4c9633366e..e5d423ef6b1 100644
--- a/studio/backend/models/__init__.py
+++ b/studio/backend/models/__init__.py
@@ -41,6 +41,7 @@ from .export import (
ExportBaseModelRequest,
ExportGGUFRequest,
ExportLoRAAdapterRequest,
+ LlmCompressorExportProbeResponse,
)
from .users import Token
from .inference import (
@@ -98,6 +99,7 @@ __all__ = [
"ExportBaseModelRequest",
"ExportGGUFRequest",
"ExportLoRAAdapterRequest",
+ "LlmCompressorExportProbeResponse",
"Token",
"LoadRequest",
"UnloadRequest",
diff --git a/studio/backend/models/export.py b/studio/backend/models/export.py
index 6d400f1c942..96806c43eea 100644
--- a/studio/backend/models/export.py
+++ b/studio/backend/models/export.py
@@ -176,6 +176,11 @@ class ExportMergedModelRequest(ExportCommonOptions):
"When set, it overrides format_type. Lets the export UI expose the full set of formats "
"beyond the quick buttons.",
)
+ install_missing_dependencies: bool = Field(
+ False,
+ description = "User consent to install llm-compressor (or its shadow runtime) for "
+ "compressed-tensors export.",
+ )
class ExportBaseModelRequest(ExportCommonOptions):
@@ -251,3 +256,19 @@ class ExportLoRAAdapterRequest(ExportCommonOptions):
description = "GGUF LoRA output float type (only used when gguf=True). "
"Q8_0 falls back to F16 per tensor for dims not divisible by the block size (32).",
)
+
+
+class LlmCompressorExportProbeResponse(BaseModel):
+ ready: bool
+ needs_consent: bool
+ consent_kind: Optional[Literal["shadow", "workspace"]] = None
+ install_summary: Optional[str] = None
+ workspace_install_command: str
+ shadow_path: str
+ autoinstall_disabled: bool
+ shadow_disabled: bool
+ offline: bool
+ blocked_reason: Optional[str] = None
+ python_executable: str
+ has_pip: bool
+ has_uv: bool
diff --git a/studio/backend/routes/export.py b/studio/backend/routes/export.py
index 306c04e9856..0df873c1314 100644
--- a/studio/backend/routes/export.py
+++ b/studio/backend/routes/export.py
@@ -49,6 +49,7 @@ from models import (
ExportBaseModelRequest,
ExportGGUFRequest,
ExportLoRAAdapterRequest,
+ LlmCompressorExportProbeResponse,
)
router = APIRouter()
@@ -382,6 +383,7 @@ async def export_merged_model(
),
private = request.private,
compressed_method = request.compressed_method,
+ install_missing_dependencies = request.install_missing_dependencies,
)
if not success:
@@ -406,6 +408,15 @@ async def export_merged_model(
)
[email protected]("/llm-compressor-probe", response_model = LlmCompressorExportProbeResponse)
+async def probe_llm_compressor_export(current_subject: str = Depends(get_current_subject)):
+ del current_subject
+ from utils.llm_compressor_export import probe_llm_compressor_for_compressed_export
+ return LlmCompressorExportProbeResponse(
+ **probe_llm_compressor_for_compressed_export(),
+ )
+
+
@router.post("/export/base", response_model = ExportOperationResponse)
async def export_base_model(
request: ExportBaseModelRequest,
diff --git a/studio/backend/tests/test_export_absolute_paths.py b/studio/backend/tests/test_export_absolute_paths.py
index 7d54c467ae4..6005a559867 100644
--- a/studio/backend/tests/test_export_absolute_paths.py
+++ b/studio/backend/tests/test_export_absolute_paths.py
@@ -208,6 +208,7 @@ def _install_lightweight_backend_stubs(monkeypatch):
"ExportBaseModelRequest",
"ExportGGUFRequest",
"ExportLoRAAdapterRequest",
+ "LlmCompressorExportProbeResponse",
):
setattr(models_pkg, name, object)
models_pkg.LocalModelInfo = _LocalModelInfo
diff --git a/studio/backend/tests/test_llm_compressor_export_consent_flag.py b/studio/backend/tests/test_llm_compressor_export_consent_flag.py
new file mode 100644
index 00000000000..b1ec1a87d20
--- /dev/null
+++ b/studio/backend/tests/test_llm_compressor_export_consent_flag.py
@@ -0,0 +1,99 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+import types
+from pathlib import Path
+
+import pytest
+
+
+_SPEC = importlib.util.spec_from_file_location(
+ "llm_compressor_consent_hub_push", Path(__file__).with_name("test_export_hub_push.py")
+)
+_HUB = importlib.util.module_from_spec(_SPEC)
+_SPEC.loader.exec_module(_HUB)
+
+
+class _CompressedModel(_HUB._Model):
+ def __init__(self):
+ super().__init__()
+ self.kwargs = []
+
+ def save_pretrained_merged(
+ self,
+ save_directory,
+ tokenizer,
+ save_method = None,
+ token = None,
+ install_missing_dependencies = True,
+ ):
+ self.kwargs.append(install_missing_dependencies)
+ output = Path(f"{save_directory}-FP8-Dynamic")
+ output.mkdir(parents = True, exist_ok = True)
+ (output / "model.safetensors").write_bytes(b"weights")
+
+
+def _compressed_backend(
+ monkeypatch,
+ shadow_calls,
+ shadow_disabled = False,
+ shadow_pp = None,
+):
+ backend = _HUB._non_mlx_backend(monkeypatch, "test_llm_compressor_consent_backend", [], {})
+ backend.current_model = _CompressedModel()
+ export_module = sys.modules["test_llm_compressor_consent_backend"]
+ monkeypatch.setattr(export_module, "_has_nvidia_gpu", lambda: True)
+ monkeypatch.setattr(export_module, "_compressed_export_supported", lambda: True)
+
+ us = sys.modules["unsloth.save"]
+ us._normalize_torchao_method = lambda method: None
+ us._normalize_compressed_method = lambda alias: ("fp8", "FP8_DYNAMIC", "FP8-Dynamic")
+ us._COMPRESSED_QUANTIZE_PYTHONPATH_ENV = "UNSLOTH_TEST_COMPRESSED_PYTHONPATH"
+ us._transformers_exceeds_llm_compressor_ceiling = lambda: (False, "4.57.6")
+
+ tv = types.ModuleType("utils.transformers_version")
+
+ def llmcompressor_shadow_pythonpath(*, allow_provision = False):
+ shadow_calls.append(allow_provision)
+ return shadow_pp if allow_provision and not shadow_disabled else None
+
+ tv.llmcompressor_shadow_pythonpath = llmcompressor_shadow_pythonpath
+ tv._llmcompressor_main_disabled = lambda: shadow_disabled
+ tv._env_offline = lambda: False
+ monkeypatch.setitem(sys.modules, "utils.transformers_version", tv)
+ return backend
+
+
+ "consented, shadow_disabled, shadow_pp, expected",
+ [
+ (False, False, None, False),
+ (False, True, None, False),
+ # Workspace consent (shadow disabled) authorizes the library install.
+ (True, True, None, True),
+ (True, False, "/shadow", True),
+ # Shadow consent whose provisioning failed must not install into the Studio interpreter.
+ (True, False, None, False),
+ ],
+)
+def test_compressed_export_states_consent_explicitly(
+ tmp_path, monkeypatch, consented, shadow_disabled, shadow_pp, expected
+):
+ # unsloth.save defaults install_missing_dependencies to True, so an unconsented export must pass False.
+ shadow_calls: list = []
+ backend = _compressed_backend(monkeypatch, shadow_calls, shadow_disabled, shadow_pp)
+
+ success, message, output_path = backend.export_merged_model(
+ str(tmp_path / "export"),
+ format_type = "FP8 (compressed-tensors)",
+ install_missing_dependencies = consented,
+ )
+
+ assert success is True, message
+ assert backend.current_model.kwargs == [expected]
+ assert shadow_calls == [consented]
+ assert output_path.endswith("export-FP8-Dynamic")
diff --git a/studio/backend/tests/test_llm_compressor_export_probe.py b/studio/backend/tests/test_llm_compressor_export_probe.py
new file mode 100644
index 00000000000..1423b38e68b
--- /dev/null
+++ b/studio/backend/tests/test_llm_compressor_export_probe.py
@@ -0,0 +1,86 @@
+# 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 ast
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+_BACKEND = Path(__file__).resolve().parent.parent
+_SAVE_PY = _BACKEND.parents[1] / "unsloth" / "save.py"
+
+
+def lce():
+ # Imported per test: a collection-time import of utils.transformers_version reorders the
+ # utils.hardware import chain other modules rely on.
+ import utils.llm_compressor_export as module
+ return module
+
+
+ "shadow_valid, shadow_disabled, offline, workspace_ok, autoinstall_off, ready, kind, blocked",
+ [
+ (True, False, False, False, False, True, None, False),
+ (False, False, False, False, False, False, "shadow", False),
+ # export.py prefers the shadow over a workspace copy, so that still needs consent.
+ (False, False, False, True, False, False, "shadow", False),
+ (False, True, False, True, False, True, None, False),
+ (False, False, True, True, False, True, None, False),
+ (False, True, False, False, False, False, "workspace", False),
+ (False, True, False, False, True, False, None, True),
+ (True, True, False, False, False, False, "workspace", False),
+ (True, True, False, True, False, True, None, False),
+ ],
+)
+def test_probe_routing(
+ lce,
+ monkeypatch,
+ shadow_valid,
+ shadow_disabled,
+ offline,
+ workspace_ok,
+ autoinstall_off,
+ ready,
+ kind,
+ blocked,
+):
+ monkeypatch.setattr(lce, "_llmcompressor_shadow_is_valid", lambda: shadow_valid)
+ monkeypatch.setattr(lce, "_llmcompressor_main_disabled", lambda: shadow_disabled)
+ monkeypatch.setattr(lce, "_env_offline", lambda: offline)
+ monkeypatch.setattr(lce, "_workspace_llmcompressor_ok", lambda spec: workspace_ok)
+ monkeypatch.setenv(
+ "UNSLOTH_DISABLE_LLM_COMPRESSOR_AUTOINSTALL", "1" if autoinstall_off else "0"
+ )
+ probe = lce.probe_llm_compressor_for_compressed_export()
+ assert probe["ready"] is ready
+ assert probe["consent_kind"] == kind
+ assert probe["needs_consent"] is (kind is not None)
+ assert bool(probe["blocked_reason"]) is blocked
+
+
+def test_spec_matches_save_py(lce):
+ tree = ast.parse(_SAVE_PY.read_text(encoding = "utf-8"))
+ expected = next(
+ ast.literal_eval(n.value)
+ for n in tree.body
+ if isinstance(n, ast.Assign)
+ and any(getattr(t, "id", None) == "_LLM_COMPRESSOR_SPEC" for t in n.targets)
+ )
+ assert lce._LLM_COMPRESSOR_SPEC == expected
+ assert expected in lce.probe_llm_compressor_for_compressed_export()["workspace_install_command"]
+
+
+def test_probe_does_not_import_unsloth_or_llmcompressor():
+ code = (
+ "import sys\n"
+ "from utils.llm_compressor_export import probe_llm_compressor_for_compressed_export as p\n"
+ "p()\n"
+ "bad = [m for m in ('unsloth', 'llmcompressor', 'torch') if m in sys.modules]\n"
+ "print(bad)\n"
+ "sys.exit(1 if bad else 0)\n"
+ )
+ r = subprocess.run([sys.executable, "-c", code], cwd = _BACKEND, capture_output = True, text = True)
+ assert r.returncode == 0, r.stdout + r.stderr
diff --git a/studio/backend/utils/llm_compressor_export.py b/studio/backend/utils/llm_compressor_export.py
new file mode 100644
index 00000000000..3c2fb2c4be1
--- /dev/null
+++ b/studio/backend/utils/llm_compressor_export.py
@@ -0,0 +1,99 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Consent probe for FP8/FP4 compressed-tensors export (llm-compressor)."""
+
+from __future__ import annotations
+
+import importlib.metadata
+import importlib.util
+import os
+import shutil
+import sys
+from typing import Any, Dict
+
+from utils.transformers_version import (
+ _VENV_LLMCOMPRESSOR_DIR,
+ _env_offline,
+ _llmcompressor_main_disabled,
+ _llmcompressor_shadow_is_valid,
+)
+
+
+# unsloth/save.py's _LLM_COMPRESSOR_SPEC (drift-tested). Not imported: this runs in the Studio
+# parent, which must not pull in unsloth / torch (see main.py).
+_LLM_COMPRESSOR_SPEC = "llmcompressor>=0.6.0,<=0.12.0"
+
+
+def _workspace_llmcompressor_ok(spec: str) -> bool:
+ try:
+ from packaging.requirements import Requirement
+ version = importlib.metadata.version("llmcompressor")
+ return Requirement(spec).specifier.contains(version, prereleases = True)
+ except Exception:
+ return False
+
+
+def probe_llm_compressor_for_compressed_export() -> Dict[str, Any]:
+ """Mirror export.py's runtime choice (shadow first, else workspace) without installing anything."""
+ spec = _LLM_COMPRESSOR_SPEC
+ shadow_valid = _llmcompressor_shadow_is_valid()
+ shadow_disabled = _llmcompressor_main_disabled()
+ offline = _env_offline()
+ autoinstall_disabled = os.environ.get(
+ "UNSLOTH_DISABLE_LLM_COMPRESSOR_AUTOINSTALL", "0"
+ ).lower() not in ("0", "", "false", "no")
+ workspace_ok = _workspace_llmcompressor_ok(spec)
+ # Same pip-first choice as save.py's llm_compressor_manual_install_command.
+ has_pip = importlib.util.find_spec("pip") is not None
+
+ # Any provisionable shadow is asked for even when the workspace copy exists: export.py prefers it,
+ # and the workspace copy cannot run models above its transformers ceiling.
+ consent_kind = None
+ install_summary = None
+ blocked_reason = None
+ # export.py ignores even a valid shadow once UNSLOTH_DISABLE_LLMCOMPRESSOR_MAIN is set.
+ if shadow_valid and not shadow_disabled:
+ ready = True
+ elif not shadow_disabled and not offline:
+ ready = False
+ consent_kind = "shadow"
+ install_summary = (
+ f"Unsloth will provision a one-time llm-compressor runtime at "
+ f"{_VENV_LLMCOMPRESSOR_DIR} (pinned packages, your torch is not upgraded)."
+ )
+ elif workspace_ok:
+ ready = True
+ elif not autoinstall_disabled:
+ ready = False
+ consent_kind = "workspace"
+ install_summary = (
+ "Unsloth will install a pinned llm-compressor into this Studio Python "
+ "environment (torch and transformers stay pinned to your current versions)."
+ )
+ else:
+ ready = False
+ blocked_reason = (
+ "llm-compressor is not installed and automatic installation is disabled via "
+ "UNSLOTH_DISABLE_LLM_COMPRESSOR_AUTOINSTALL. Install it manually or unset that variable."
+ )
+
+ return {
+ "ready": ready,
+ "needs_consent": consent_kind is not None,
+ "consent_kind": consent_kind,
+ "install_summary": install_summary,
+ "workspace_install_command": (
+ f"{sys.executable} -m pip install '{spec}'"
+ if has_pip
+ else f"uv pip install --python {sys.executable} '{spec}'"
+ ),
+ "shadow_path": _VENV_LLMCOMPRESSOR_DIR,
+ "autoinstall_disabled": autoinstall_disabled,
+ "shadow_disabled": shadow_disabled,
+ "offline": offline,
+ "blocked_reason": blocked_reason,
+ "python_executable": sys.executable,
+ "has_pip": has_pip,
+ "has_uv": bool(shutil.which("uv")),
+ }
diff --git a/studio/backend/utils/transformers_version.py b/studio/backend/utils/transformers_version.py
index 705edec0682..b3c39c063f0 100644
--- a/studio/backend/utils/transformers_version.py
+++ b/studio/backend/utils/transformers_version.py
@@ -3826,14 +3826,15 @@ def _ensure_venv_llmcompressor_exists() -> bool:
return False
-def llmcompressor_shadow_pythonpath() -> str | None:
- """Provision (lazily) the llm-compressor-main shadow and return its sys.path entry, or None.
-
- Returns None when the shadow is disabled (UNSLOTH_DISABLE_LLMCOMPRESSOR_MAIN), offline, or
- provisioning failed - callers then fall back to the fail-fast path.
- """
+def llmcompressor_shadow_pythonpath(*, allow_provision: bool = False) -> str | None:
+ """Return the llm-compressor-main shadow's sys.path entry, provisioning a missing one only with
+ allow_provision (the user's consent), or None (disabled, offline, not consented, failed)."""
if _llmcompressor_main_disabled():
return None
+ if _llmcompressor_shadow_is_valid():
+ return _VENV_LLMCOMPRESSOR_DIR
+ if not allow_provision:
+ return None
if _ensure_venv_llmcompressor_exists():
return _VENV_LLMCOMPRESSOR_DIR
return None
diff --git a/studio/frontend/src/app/routes/__root.tsx b/studio/frontend/src/app/routes/__root.tsx
index 35bded44922..5e478512c33 100644
--- a/studio/frontend/src/app/routes/__root.tsx
+++ b/studio/frontend/src/app/routes/__root.tsx
@@ -50,6 +50,7 @@ import {
import { useLowDiskNotice } from "@/features/settings/hooks/use-low-disk-notice";
import { useTrainingUnloadGuard } from "@/features/training";
import { TransformersUpgradeDialog } from "@/features/transformers-upgrade";
+import { LlmCompressorConsentDialog } from "@/features/export/components/llm-compressor-consent-dialog";
import { useNativePathLeasesSupported } from "@/features/native-intents";
import { useRagAvailabilityStore } from "@/features/rag";
import { useIsMobileShell } from "@/hooks/use-mobile";
@@ -677,6 +678,7 @@ function RootLayout() {
<HfTokenWarningDialog />
<RemoteCodeConsentDialog />
<TransformersUpgradeDialog />
+ <LlmCompressorConsentDialog />
{/* At the root, not under /chat: a swap can start from the Hub too. */}
<StopRunningChatsDialog />
{!hideNavbar && <CommandPalette />}
diff --git a/studio/frontend/src/features/export/api/export-api.ts b/studio/frontend/src/features/export/api/export-api.ts
index 7cd75c99bf7..2b67d3faeab 100644
--- a/studio/frontend/src/features/export/api/export-api.ts
+++ b/studio/frontend/src/features/export/api/export-api.ts
@@ -140,6 +140,7 @@ export async function exportMerged(params: {
repo_id?: string | null;
hf_token?: string | null;
private?: boolean;
+ install_missing_dependencies?: boolean;
}): Promise<ExportOperationResponse> {
const response = await authFetch("/api/export/export/merged", {
method: "POST",
diff --git a/studio/frontend/src/features/export/api/llm-compressor-consent-api.ts b/studio/frontend/src/features/export/api/llm-compressor-consent-api.ts
new file mode 100644
index 00000000000..2d2f52cae77
--- /dev/null
+++ b/studio/frontend/src/features/export/api/llm-compressor-consent-api.ts
@@ -0,0 +1,31 @@
+// 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 { authFetch } from "@/features/auth";
+import { readFastApiError } from "@/lib/format-fastapi-error";
+
+export type LlmCompressorConsentKind = "shadow" | "workspace";
+
+export interface LlmCompressorExportProbe {
+ ready: boolean;
+ needs_consent: boolean;
+ consent_kind: LlmCompressorConsentKind | null;
+ install_summary: string | null;
+ workspace_install_command: string;
+ shadow_path: string;
+ autoinstall_disabled: boolean;
+ shadow_disabled: boolean;
+ offline: boolean;
+ blocked_reason: string | null;
+ python_executable: string;
+ has_pip: boolean;
+ has_uv: boolean;
+}
+
+export async function fetchLlmCompressorProbe(): Promise<LlmCompressorExportProbe> {
+ const response = await authFetch("/api/export/llm-compressor-probe");
+ if (!response.ok) {
+ throw new Error(await readFastApiError(response));
+ }
+ return (await response.json()) as LlmCompressorExportProbe;
+}
diff --git a/studio/frontend/src/features/export/components/llm-compressor-consent-dialog.tsx b/studio/frontend/src/features/export/components/llm-compressor-consent-dialog.tsx
new file mode 100644
index 00000000000..ea388174daf
--- /dev/null
+++ b/studio/frontend/src/features/export/components/llm-compressor-consent-dialog.tsx
@@ -0,0 +1,92 @@
+// 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 {
+ AlertDialog,
+ AlertDialogAction,
+ AlertDialogCancel,
+ AlertDialogContent,
+ AlertDialogDescription,
+ AlertDialogFooter,
+ AlertDialogHeader,
+ AlertDialogTitle,
+} from "@/components/ui/alert-dialog";
+import { PackageIcon } from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
+import { useLlmCompressorConsentStore } from "../stores/llm-compressor-consent-store";
+
+export function LlmCompressorConsentDialog() {
+ const open = useLlmCompressorConsentStore((s) => s.open);
+ const probe = useLlmCompressorConsentStore((s) => s.probe);
+ const resolve = useLlmCompressorConsentStore((s) => s.resolve);
+
+ const blocked = Boolean(probe?.blocked_reason);
+ const summary =
+ probe?.install_summary ??
+ "This export needs llm-compressor, which is not installed in this environment.";
+
+ return (
+ <AlertDialog
+ open={open}
+ onOpenChange={(next) => {
+ if (!next) resolve(false);
+ }}
+ >
+ <AlertDialogContent className="max-w-lg">
+ <AlertDialogHeader className="min-w-0">
+ <div className="flex w-full min-w-0 items-start gap-3">
+ <div className="flex size-9 shrink-0 items-center justify-center rounded-full bg-blue-500/10 text-blue-600 dark:text-blue-400">
+ <HugeiconsIcon icon={PackageIcon} className="size-5" />
+ </div>
+ <div className="min-w-0 flex-1 space-y-3">
+ <div className="space-y-1">
+ <AlertDialogTitle>
+ {blocked ? "Cannot install llm-compressor" : "Install llm-compressor?"}
+ </AlertDialogTitle>
+ <AlertDialogDescription asChild>
+ <div className="space-y-2 text-sm text-muted-foreground">
+ {blocked ? (
+ <p className="rounded-lg border border-red-500/30 bg-red-500/10 px-3 py-2 text-xs text-red-600 [overflow-wrap:anywhere] dark:text-red-400">
+ {probe?.blocked_reason}
+ </p>
+ ) : (
+ <>
+ <p className="[overflow-wrap:anywhere]">{summary}</p>
+ {probe?.consent_kind === "workspace" ? (
+ <p className="rounded-md border bg-muted/40 px-3 py-2 font-mono text-xs text-foreground break-all">
+ {probe.workspace_install_command}
+ </p>
+ ) : probe?.consent_kind === "shadow" ? (
+ <p className="text-xs">
+ Target:{" "}
+ <span className="font-mono text-foreground break-all">
+ {probe.shadow_path}
+ </span>
+ </p>
+ ) : null}
+ <p className="text-xs">
+ Interpreter:{" "}
+ <span className="font-mono text-foreground break-all">
+ {probe?.python_executable}
+ </span>
+ </p>
+ </>
+ )}
+ </div>
+ </AlertDialogDescription>
+ </div>
+ </div>
+ </div>
+ </AlertDialogHeader>
+ <AlertDialogFooter>
+ <AlertDialogCancel>Cancel</AlertDialogCancel>
+ {!blocked ? (
+ <AlertDialogAction onClick={() => resolve(true)}>
+ Install and continue
+ </AlertDialogAction>
+ ) : null}
+ </AlertDialogFooter>
+ </AlertDialogContent>
+ </AlertDialog>
+ );
+}
diff --git a/studio/frontend/src/features/export/export-page.tsx b/studio/frontend/src/features/export/export-page.tsx
index 858f571e4ee..c3754bb64e4 100644
--- a/studio/frontend/src/features/export/export-page.tsx
+++ b/studio/frontend/src/features/export/export-page.tsx
@@ -85,6 +85,7 @@ import {
refreshCheckpoints,
refreshLocalModels,
} from "./export-navigation-cache";
+import { confirmLlmCompressorInstallIfNeeded } from "./hooks/use-llm-compressor-consent";
import { useExportSizeEstimate } from "./hooks/use-export-size-estimate";
import {
isExportPanelActive,
@@ -796,6 +797,15 @@ export function ExportPage() {
if (!remoteCodeOk) return;
}
+ let installMissingDependencies = false;
+ if (effectiveMethod === "merged") {
+ const llmCompressor = await confirmLlmCompressorInstallIfNeeded(
+ selectedFormats,
+ );
+ if (!llmCompressor.ok) return;
+ installMissingDependencies = llmCompressor.installMissingDependencies;
+ }
+
void runExport({
sourceMode,
checkpointPath,
@@ -821,6 +831,7 @@ export function ExportPage() {
repoId,
token,
privateRepo,
+ installMissingDependencies,
baseModelId: selectedModelData?.base_model ?? undefined,
summary: {
baseModelName: sourceBaseModelName,
diff --git a/studio/frontend/src/features/export/hooks/use-llm-compressor-consent.ts b/studio/frontend/src/features/export/hooks/use-llm-compressor-consent.ts
new file mode 100644
index 00000000000..2c8bd1382b5
--- /dev/null
+++ b/studio/frontend/src/features/export/hooks/use-llm-compressor-consent.ts
@@ -0,0 +1,38 @@
+// 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 { MERGED_FORMATS } from "../constants";
+import { fetchLlmCompressorProbe } from "../api/llm-compressor-consent-api";
+import { useLlmCompressorConsentStore } from "../stores/llm-compressor-consent-store";
+
+export function mergedFormatNeedsLlmCompressor(formatValue: string): boolean {
+ const fmt = MERGED_FORMATS.find((f) => f.value === formatValue);
+ return fmt?.backend === "compressed";
+}
+
+export async function confirmLlmCompressorInstallIfNeeded(
+ selectedFormatValues: string[],
+): Promise<{ ok: boolean; installMissingDependencies: boolean }> {
+ const needsCompressed = selectedFormatValues.some(mergedFormatNeedsLlmCompressor);
+ if (!needsCompressed) {
+ return { ok: true, installMissingDependencies: false };
+ }
+
+ let probe;
+ try {
+ probe = await fetchLlmCompressorProbe();
+ } catch {
+ // An unreachable probe must not swallow the click: the export then fails with the install command.
+ return { ok: true, installMissingDependencies: false };
+ }
+ if (probe.ready) {
+ return { ok: true, installMissingDependencies: false };
+ }
+ if (probe.blocked_reason || probe.needs_consent) {
+ const consented = await useLlmCompressorConsentStore
+ .getState()
+ .requestConsent(probe);
+ return { ok: consented, installMissingDependencies: consented };
+ }
+ return { ok: false, installMissingDependencies: false };
+}
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 c26958ef77c..2394a4ec7b9 100644
--- a/studio/frontend/src/features/export/stores/export-runtime-store.ts
+++ b/studio/frontend/src/features/export/stores/export-runtime-store.ts
@@ -159,6 +159,7 @@ export interface RunExportParams {
token?: string;
privateRepo: boolean;
baseModelId?: string | null;
+ installMissingDependencies?: boolean;
summary: ExportRunSummary;
}
@@ -477,6 +478,9 @@ export const useExportRuntimeStore = create<ExportRuntimeStore>()((set, get) =>
repo_id: params.repoId,
hf_token: params.token,
private: params.privateRepo,
+ install_missing_dependencies: Boolean(
+ params.installMissingDependencies,
+ ),
}),
);
if (outputPath) outputs.push({ label: sel.label, path: outputPath });
diff --git a/studio/frontend/src/features/export/stores/llm-compressor-consent-store.ts b/studio/frontend/src/features/export/stores/llm-compressor-consent-store.ts
new file mode 100644
index 00000000000..40901b8e63d
--- /dev/null
+++ b/studio/frontend/src/features/export/stores/llm-compressor-consent-store.ts
@@ -0,0 +1,35 @@
+// 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 { create } from "zustand";
+import type { LlmCompressorExportProbe } from "../api/llm-compressor-consent-api";
+
+type Resolver = (consented: boolean) => void;
+
+let pendingResolver: Resolver | null = null;
+
+interface LlmCompressorConsentStore {
+ open: boolean;
+ probe: LlmCompressorExportProbe | null;
+ requestConsent: (probe: LlmCompressorExportProbe) => Promise<boolean>;
+ resolve: (consented: boolean) => void;
+}
+
+export const useLlmCompressorConsentStore = create<LlmCompressorConsentStore>()(
+ (set) => ({
+ open: false,
+ probe: null,
+ requestConsent: (probe) =>
+ new Promise<boolean>((resolve) => {
+ pendingResolver?.(false);
+ pendingResolver = resolve;
+ set({ open: true, probe });
+ }),
+ resolve: (consented) => {
+ const resolver = pendingResolver;
+ pendingResolver = null;
+ set({ open: false, probe: null });
+ resolver?.(consented);
+ },
+ }),
+);
diff --git a/tests/studio/test_llm_compressor_export_consent.py b/tests/studio/test_llm_compressor_export_consent.py
new file mode 100644
index 00000000000..b358f30ac80
--- /dev/null
+++ b/tests/studio/test_llm_compressor_export_consent.py
@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+"""Static guards for Studio llm-compressor export consent (#8904)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+_REPO = Path(__file__).resolve().parents[2]
+
+
+def _read(rel: str) -> str:
+ return (_REPO / rel).read_text(encoding = "utf-8")
+
+
+def test_probe_route_is_registered():
+ routes = _read("studio/backend/routes/export.py")
+ assert "/llm-compressor-probe" in routes
+ assert "LlmCompressorExportProbeResponse" in routes
+
+
+def test_merged_request_accepts_install_missing_dependencies():
+ models = _read("studio/backend/models/export.py")
+ assert "install_missing_dependencies: bool = Field(" in models
+
+
+def test_export_pipeline_threads_consent_flag():
+ export_py = _read("studio/backend/core/export/export.py")
+ assert "install_missing_dependencies" in export_py
+ assert "allow_provision = install_missing_dependencies" in export_py
+ worker = _read("studio/backend/core/export/worker.py")
+ assert 'cmd.get("install_missing_dependencies"' in worker
+ orch = _read("studio/backend/core/export/orchestrator.py")
+ assert '"install_missing_dependencies": install_missing_dependencies' in orch
+
+
+def test_shadow_pythonpath_requires_explicit_provision():
+ tv = _read("studio/backend/utils/transformers_version.py")
+ assert "def llmcompressor_shadow_pythonpath(*, allow_provision: bool = False)" in tv
+
+
+def test_frontend_export_wires_consent_dialog():
+ root = _read("studio/frontend/src/app/routes/__root.tsx")
+ assert "LlmCompressorConsentDialog" in root
+ page = _read("studio/frontend/src/features/export/export-page.tsx")
+ assert "confirmLlmCompressorInstallIfNeeded" in page
+ assert "installMissingDependencies" in page