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: provide Git lazily for FP8/FP4 export instead of at install time (#13084)

Daniel Han6b833e3f230a
diff --git a/studio/backend/tests/test_git_tool.py b/studio/backend/tests/test_git_tool.py
new file mode 100644
index 00000000000..6c7148f2110
--- /dev/null
+++ b/studio/backend/tests/test_git_tool.py
@@ -0,0 +1,194 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Git is provided lazily by the feature that needs it, never by the installer."""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import zipfile
+
+import pytest
+
+from utils import git_tool
+
+
+def _zip_bytes(entries: dict[str, bytes]) -> bytes:
+ buf = io.BytesIO()
+ with zipfile.ZipFile(buf, "w") as zf:
+ for name, data in entries.items():
+ zf.writestr(name, data)
+ return buf.getvalue()
+
+
+class _Response(io.BytesIO):
+ def __enter__(self):
+ return self
+
+ def __exit__(self, *exc):
+ return False
+
+
+def windows_without_git(monkeypatch, tmp_path):
+ monkeypatch.setattr(git_tool, "_IS_WINDOWS", True)
+ monkeypatch.setattr(git_tool.shutil, "which", lambda name: None)
+ monkeypatch.setattr(git_tool, "studio_root", lambda: tmp_path)
+ monkeypatch.setattr(git_tool, "_mingit_flavor", lambda: "64-bit")
+ # git.exe cannot run here: a present, non-empty launcher stands in for a working one.
+ monkeypatch.setattr(
+ git_tool,
+ "_git_works",
+ lambda exe: git_tool.Path(exe).is_file() and git_tool.Path(exe).read_bytes() == b"MZ",
+ )
+ return tmp_path
+
+
+def _serve(
+ monkeypatch,
+ payload: bytes,
+ *,
+ digest: str | None = None,
+):
+ calls = []
+ monkeypatch.setitem(
+ git_tool._MINGIT_SHA256, "64-bit", digest or hashlib.sha256(payload).hexdigest()
+ )
+
+ def fake_urlopen(request, timeout = None):
+ calls.append(request.full_url)
+ return _Response(payload)
+
+ monkeypatch.setattr(git_tool.urllib.request, "urlopen", fake_urlopen)
+ return calls
+
+
+def test_working_git_on_path_is_used_as_is(monkeypatch):
+ monkeypatch.setattr(git_tool.shutil, "which", lambda name: "/usr/bin/git")
+ monkeypatch.setattr(git_tool, "_git_works", lambda exe: True)
+ monkeypatch.setattr(
+ git_tool.urllib.request, "urlopen", lambda *a, **k: pytest.fail("downloaded")
+ )
+ assert git_tool.ensure_git() is None
+
+
+def test_missing_git_off_windows_explains_how_to_install(monkeypatch):
+ monkeypatch.setattr(git_tool, "_IS_WINDOWS", False)
+ monkeypatch.setattr(git_tool.shutil, "which", lambda name: None)
+ with pytest.raises(git_tool.GitUnavailable, match = "package manager"):
+ git_tool.ensure_git()
+
+
+def test_windows_fetches_pinned_mingit_once_into_studio_home(monkeypatch, windows_without_git):
+ calls = _serve(monkeypatch, _zip_bytes({"cmd/git.exe": b"MZ", "mingw64/bin/git.exe": b"MZ"}))
+ first = git_tool.ensure_git()
+ second = git_tool.ensure_git()
+ root = windows_without_git / "tools" / f"mingit-{git_tool.MINGIT_VERSION}-64-bit"
+ assert first == second == str(root / "cmd")
+ assert (root / "cmd" / "git.exe").is_file()
+ assert calls == [
+ "https://github.com/git-for-windows/git/releases/download/"
+ f"{git_tool._MINGIT_TAG}/MinGit-{git_tool.MINGIT_VERSION}-64-bit.zip"
+ ]
+
+
+def test_checksum_mismatch_installs_nothing(monkeypatch, windows_without_git):
+ _serve(monkeypatch, _zip_bytes({"cmd/git.exe": b"MZ"}), digest = "0" * 64)
+ with pytest.raises(git_tool.GitUnavailable, match = "sha256"):
+ git_tool.ensure_git()
+ assert not any((windows_without_git / "tools").glob("mingit-*"))
+
+
+def test_zip_entry_escaping_its_root_is_refused(monkeypatch, windows_without_git):
+ _serve(monkeypatch, _zip_bytes({"cmd/git.exe": b"MZ", "../evil.txt": b"x"}))
+ with pytest.raises(git_tool.GitUnavailable, match = "outside its root"):
+ git_tool.ensure_git()
+ assert not (windows_without_git / "tools" / "evil.txt").exists()
+
+
+def test_offline_windows_without_git_does_not_download(monkeypatch, windows_without_git):
+ monkeypatch.setattr(
+ git_tool.urllib.request, "urlopen", lambda *a, **k: pytest.fail("downloaded")
+ )
+ with pytest.raises(git_tool.GitUnavailable, match = "offline"):
+ git_tool.ensure_git(allow_download = False)
+
+
+def test_network_error_becomes_git_unavailable(monkeypatch, windows_without_git):
+ def boom(*a, **k):
+ raise OSError("connection reset")
+
+ monkeypatch.setattr(git_tool.urllib.request, "urlopen", boom)
+ with pytest.raises(git_tool.GitUnavailable, match = "connection reset"):
+ git_tool.ensure_git()
+
+
+def test_with_git_on_path_prepends_for_the_child_only():
+ env = {"Path": r"C:\Windows"}
+ out = git_tool.with_git_on_path(env, r"C:\s\tools\mingit\cmd")
+ assert out["Path"].startswith(r"C:\s\tools\mingit\cmd" + git_tool.os.pathsep)
+ assert env == {"Path": r"C:\Windows"}
+ assert git_tool.with_git_on_path(env, None) is env
+
+
+def test_llmcompressor_shadow_gets_git_on_the_install_path(monkeypatch, tmp_path):
+ from utils import transformers_version as tv
+
+ monkeypatch.setattr(tv, "_llmcompressor_shadow_is_valid", lambda: False)
+ monkeypatch.setattr(tv, "_llmcompressor_main_disabled", lambda: False)
+ monkeypatch.setattr(tv, "_env_offline", lambda: False)
+ monkeypatch.setattr(tv, "_VENV_LLMCOMPRESSOR_DIR", str(tmp_path / "shadow"))
+ monkeypatch.setattr(git_tool, "ensure_git", lambda **k: "/studio/tools/mingit/cmd")
+ seen = []
+
+ class _Done:
+ returncode = 0
+ stdout = ""
+
+ def fake_run(cmd, **kwargs):
+ env = kwargs["env"]
+ seen.append(next(v for k, v in env.items() if k.upper() == "PATH"))
+ return _Done()
+
+ monkeypatch.setattr(tv.subprocess, "run", fake_run)
+ assert tv._ensure_venv_llmcompressor_exists() is True
+ assert seen and seen[0].startswith("/studio/tools/mingit/cmd" + git_tool.os.pathsep)
+
+
+def test_llmcompressor_shadow_fails_cleanly_without_git(monkeypatch, tmp_path):
+ from utils import transformers_version as tv
+
+ monkeypatch.setattr(tv, "_llmcompressor_shadow_is_valid", lambda: False)
+ monkeypatch.setattr(tv, "_llmcompressor_main_disabled", lambda: False)
+ monkeypatch.setattr(tv, "_env_offline", lambda: False)
+ monkeypatch.setattr(tv, "_VENV_LLMCOMPRESSOR_DIR", str(tmp_path / "shadow"))
+
+ def no_git(**k):
+ raise git_tool.GitUnavailable("Git is required")
+
+ monkeypatch.setattr(git_tool, "ensure_git", no_git)
+ monkeypatch.setattr(tv.subprocess, "run", lambda *a, **k: pytest.fail("ran an install"))
+ assert tv._ensure_venv_llmcompressor_exists() is False
+
+
[email protected](git_tool.os.name != "nt", reason = "runs the real MinGit git.exe")
+def test_real_mingit_runs_on_windows(monkeypatch, tmp_path):
+ monkeypatch.setattr(git_tool.shutil, "which", lambda name: None)
+ monkeypatch.setattr(git_tool, "studio_root", lambda: tmp_path)
+ git_dir = git_tool.ensure_git()
+ out = git_tool.subprocess.run(
+ [str(git_tool.Path(git_dir) / "git.exe"), "--version"],
+ capture_output = True,
+ text = True,
+ check = True,
+ )
+ assert git_tool.MINGIT_VERSION.rsplit(".", 1)[0] in out.stdout
+
+
+def test_bundled_git_uses_the_windows_certificate_store():
+ env = git_tool.with_git_on_path({"PATH": "x", "GIT_CONFIG_COUNT": "1"}, r"C:\s\mingit\cmd")
+ assert env["GIT_CONFIG_COUNT"] == "2"
+ assert (env["GIT_CONFIG_KEY_1"], env["GIT_CONFIG_VALUE_1"]) == ("http.sslBackend", "schannel")
+ assert "GIT_CONFIG_COUNT" not in git_tool.with_git_on_path({"PATH": "x"}, None)
diff --git a/studio/backend/utils/git_tool.py b/studio/backend/utils/git_tool.py
new file mode 100644
index 00000000000..42e3c68ae74
--- /dev/null
+++ b/studio/backend/utils/git_tool.py
@@ -0,0 +1,144 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Git on demand for ``git+`` installs. A working system Git is used as is; on Windows a missing one
+is fetched once as portable MinGit into the Studio home (no admin, no winget) and put on the child's
+PATH only. Elsewhere installing Git needs root, so callers get an error with instructions."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import platform
+import shutil
+import subprocess
+import tempfile
+import urllib.request
+import zipfile
+from pathlib import Path
+from typing import Optional
+
+from filelock import FileLock
+
+from utils.paths.storage_roots import studio_root
+
+# Bump all three together; digests are GitHub's published asset digests for that release.
+MINGIT_VERSION = "2.56.0.2"
+_MINGIT_TAG = "v2.56.0.windows.2"
+_MINGIT_SHA256 = {
+ "64-bit": "da35e72aa21c005a5a0d298cfbae110bc1609a815730ea0dde84b01a1b3cd3be",
+ "arm64": "38b33dc6024026e3315cf88ab2cfea65205bbd7bb3a8e824bd21c8ad4fe609a7",
+}
+
+
+_IS_WINDOWS = os.name == "nt"
+
+
+class GitUnavailable(RuntimeError):
+ pass
+
+
+def _git_works(exe: str) -> bool:
+ try:
+ return (
+ subprocess.run(
+ [exe, "--version"],
+ stdout = subprocess.DEVNULL,
+ stderr = subprocess.DEVNULL,
+ timeout = 30,
+ ).returncode
+ == 0
+ )
+ except (OSError, subprocess.SubprocessError):
+ return False
+
+
+def _mingit_flavor() -> str:
+ arch = (
+ os.environ.get("PROCESSOR_ARCHITEW6432")
+ or os.environ.get("PROCESSOR_ARCHITECTURE")
+ or platform.machine()
+ )
+ return "arm64" if arch.strip().lower() == "arm64" else "64-bit"
+
+
+def _mingit_dir(flavor: str) -> Path:
+ return studio_root() / "tools" / f"mingit-{MINGIT_VERSION}-{flavor}"
+
+
+def _mingit_git(root: Path) -> Path:
+ return root / "cmd" / "git.exe"
+
+
+def _download_mingit(flavor: str, target: Path) -> None:
+ name = f"MinGit-{MINGIT_VERSION}-{flavor}.zip"
+ url = f"https://github.com/git-for-windows/git/releases/download/{_MINGIT_TAG}/{name}"
+ target.parent.mkdir(parents = True, exist_ok = True)
+ with tempfile.TemporaryDirectory(dir = target.parent, prefix = ".mingit-") as tmp:
+ archive = Path(tmp) / name
+ digest = hashlib.sha256()
+ request = urllib.request.Request(url, headers = {"User-Agent": "unsloth-studio"})
+ with urllib.request.urlopen(request, timeout = 300) as response, open(archive, "wb") as out:
+ while chunk := response.read(1 << 20):
+ digest.update(chunk)
+ out.write(chunk)
+ if digest.hexdigest() != _MINGIT_SHA256[flavor]:
+ raise GitUnavailable(f"{name} failed its sha256 check; not installing it")
+ staged = Path(tmp) / "mingit"
+ with zipfile.ZipFile(archive) as zf:
+ base = staged.resolve()
+ for member in zf.namelist():
+ if not (staged / member).resolve().is_relative_to(base):
+ raise GitUnavailable(f"{name} has an entry outside its root: {member}")
+ zf.extractall(staged)
+ if not _git_works(str(_mingit_git(staged))):
+ raise GitUnavailable(f"git from {name} does not run on this machine")
+ os.replace(staged, target)
+
+
+def ensure_git(*, allow_download: bool = True) -> Optional[str]:
+ """None when Git on PATH works, else a dir to prepend to a child's PATH (Windows MinGit).
+ Raises GitUnavailable when Git is missing and cannot be provided here."""
+ exe = shutil.which("git")
+ if exe and _git_works(exe):
+ return None
+ if not _IS_WINDOWS:
+ raise GitUnavailable(
+ "Git is required for this step but is not installed. Install it with your package "
+ "manager (for example `sudo apt install git` or `xcode-select --install`) and retry."
+ )
+ flavor = _mingit_flavor()
+ root = _mingit_dir(flavor)
+ if _git_works(str(_mingit_git(root))):
+ return str(root / "cmd")
+ if not allow_download:
+ raise GitUnavailable("Git is required for this step and this process is offline.")
+ root.parent.mkdir(parents = True, exist_ok = True)
+ with FileLock(str(root.parent / ".mingit.lock"), timeout = 600):
+ if not _git_works(str(_mingit_git(root))):
+ if root.exists():
+ shutil.rmtree(root, ignore_errors = True)
+ try:
+ _download_mingit(flavor, root)
+ except GitUnavailable:
+ raise
+ except Exception as exc: # network, disk, bad zip
+ raise GitUnavailable(f"Could not download portable Git (MinGit): {exc}") from exc
+ return str(root / "cmd")
+
+
+def with_git_on_path(env: dict, git_dir: Optional[str]) -> dict:
+ if not git_dir:
+ return env
+ env = dict(env)
+ key = next((k for k in env if k.upper() == "PATH"), "PATH")
+ env[key] = git_dir + os.pathsep + env.get(key, "")
+ # MinGit ships no installer config; schannel makes it trust the Windows certificate store.
+ try:
+ n = int(env.get("GIT_CONFIG_COUNT") or 0)
+ except ValueError:
+ n = 0
+ env[f"GIT_CONFIG_KEY_{n}"] = "http.sslBackend"
+ env[f"GIT_CONFIG_VALUE_{n}"] = "schannel"
+ env["GIT_CONFIG_COUNT"] = str(n + 1)
+ return env
diff --git a/studio/backend/utils/transformers_version.py b/studio/backend/utils/transformers_version.py
index cf0ab115a9f..92e6855cd99 100644
--- a/studio/backend/utils/transformers_version.py
+++ b/studio/backend/utils/transformers_version.py
@@ -3808,6 +3808,15 @@ def _ensure_venv_llmcompressor_exists() -> bool:
)
return False
+ # llmcompressor is a git+ requirement, and uv / pip shell out to git for it.
+ from utils.git_tool import GitUnavailable, ensure_git, with_git_on_path
+
+ try:
+ git_dir = ensure_git()
+ except GitUnavailable as exc:
+ logger.error("Cannot provision llm-compressor-main shadow: %s", exc)
+ return False
+
logger.warning(
"Provisioning llm-compressor-main shadow at %s (one-time, ~a few hundred MB, no torch) ...",
_VENV_LLMCOMPRESSOR_DIR,
@@ -3846,8 +3855,11 @@ def _ensure_venv_llmcompressor_exists() -> bool:
text = True,
encoding = "utf-8",
errors = "replace",
- env = utf8_child_env(
- get_hf_cache_paths().child_env(child_env_without_native_path_secret())
+ env = with_git_on_path(
+ utf8_child_env(
+ get_hf_cache_paths().child_env(child_env_without_native_path_secret())
+ ),
+ git_dir,
),
**_windows_hidden_subprocess_kwargs(),
)