Skip to content

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

Stop the installers importing the download stack just to be imported (#11446)

Daniel Hanedf77d7752a4
diff --git a/studio/install_llama_prebuilt.py b/studio/install_llama_prebuilt.py
index f9d52f2a2cc..b7eeca428f9 100644
--- a/studio/install_llama_prebuilt.py
+++ b/studio/install_llama_prebuilt.py
@@ -26,23 +26,16 @@ import stat
import struct
import subprocess
import sys
-import tarfile
import tempfile
import textwrap
import time
import urllib.error
import urllib.parse
import urllib.request
-import zipfile
from collections.abc import Sequence
from contextlib import contextmanager
from dataclasses import dataclass, field, replace as dataclasses_replace
-try:
- from filelock import FileLock, Timeout as FileLockTimeout
-except ImportError:
- FileLock = None
- FileLockTimeout = None
from pathlib import Path, PurePath
from typing import Any, Callable, Iterable, Iterator, Union
diff --git a/studio/prebuilt_core.py b/studio/prebuilt_core.py
index c04e2bfc4a7..1f950f95272 100644
--- a/studio/prebuilt_core.py
+++ b/studio/prebuilt_core.py
@@ -39,13 +39,11 @@ import shutil
import socket
import subprocess
import sys
-import tarfile
import tempfile
import time
import urllib.error
import urllib.parse
import urllib.request
-import zipfile
from contextlib import contextmanager
from dataclasses import dataclass
from pathlib import Path
@@ -61,11 +59,25 @@ else:
sys.path.insert(0, _STUDIO_DIR)
from backend.utils.auth_safe import AuthSafeRedirectHandler
-try:
- from filelock import FileLock, Timeout as FileLockTimeout
-except ImportError:
- FileLock = None
- FileLockTimeout = None
+_FILELOCK_CLASSES: tuple[Any, Any] | None = None
+
+
+def filelock_classes() -> tuple[Any, Any]:
+ """``(FileLock, Timeout)``, or ``(None, None)`` when filelock is not installed.
+
+ First use, not import: filelock pulls in asyncio and costs ~25 ms, and only
+ ``install_lock`` needs it. Cached because repeating an ImportError is not cheap.
+ """
+ global _FILELOCK_CLASSES
+ if _FILELOCK_CLASSES is None:
+ try:
+ from filelock import FileLock, Timeout as FileLockTimeout
+ except ImportError:
+ _FILELOCK_CLASSES = (None, None)
+ else:
+ _FILELOCK_CLASSES = (FileLock, FileLockTimeout)
+ return _FILELOCK_CLASSES
+
# Fresh spawned interpreter, and this standalone module cannot import backend
# modules, so the gate is pasted from native_tls.py's inline_gate_source().
@@ -1101,6 +1113,9 @@ def extract_archive(archive_path: Path, destination: Path) -> None:
return normalized, resolved
def extract_zip_safely(source: Path, base: Path) -> None:
+ # Local: only an install that unpacks an archive needs these, and every CLI
+ # command imports this module.
+ import zipfile
with zipfile.ZipFile(source) as archive:
for member in archive.infolist():
target = safe_extract_path(base, member.filename)
@@ -1117,6 +1132,8 @@ def extract_archive(archive_path: Path, destination: Path) -> None:
shutil.copyfileobj(src, dst)
def extract_tar_safely(source: Path, base: Path) -> None:
+ import tarfile
+
pending_links: list[tuple[tarfile.TarInfo, Path]] = []
archive_names: set[str] = set()
with tarfile.open(source, "r:gz") as archive:
@@ -1188,6 +1205,8 @@ def restore_tar_exec_bits(archive_path: Path, destination: Path) -> None:
server binaries must stay executable on Unix."""
if os.name == "nt" or not archive_path.name.endswith(".tar.gz"):
return
+ import tarfile
+
with tarfile.open(archive_path, "r:gz") as archive:
for member in archive.getmembers():
if not (member.isfile() and member.mode & 0o111):
@@ -1204,7 +1223,8 @@ def install_lock(lock_path: Path, *, timeout: float | None = None) -> Iterator[N
seconds = INSTALL_LOCK_TIMEOUT_SECONDS if timeout is None else timeout
lock_path.parent.mkdir(parents = True, exist_ok = True)
- if FileLock is None:
+ file_lock, file_lock_timeout = filelock_classes()
+ if file_lock is None:
# Fallback lock: exclusive file creation, writing our PID so stale locks
# from crashed processes can be detected.
fd: int | None = None
@@ -1264,9 +1284,9 @@ def install_lock(lock_path: Path, *, timeout: float | None = None) -> Iterator[N
return
try:
- with FileLock(lock_path, timeout = seconds):
+ with file_lock(lock_path, timeout = seconds):
yield
- except FileLockTimeout as exc:
+ except file_lock_timeout as exc:
raise BusyInstallConflict(
f"timed out after {seconds}s waiting for concurrent install lock: {lock_path}"
) from exc
diff --git a/tests/studio/install/test_installer_import_cost.py b/tests/studio/install/test_installer_import_cost.py
new file mode 100644
index 00000000000..093a99d702b
--- /dev/null
+++ b/tests/studio/install/test_installer_import_cost.py
@@ -0,0 +1,113 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""What the installer modules may import just to be imported.
+
+Every `unsloth studio` command loads `install_llama_prebuilt`, and the desktop
+preflight loads it to stat a directory, so the module-scope import list is on the
+launch path; filelock alone costs ~25 ms because it pulls in asyncio.
+
+Pinned as "not in sys.modules" rather than as a wall-clock budget, which would flake
+on a shared runner. Fresh interpreter each time: the test session has its own imports.
+"""
+
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+PACKAGE_ROOT = Path(__file__).resolve().parents[3]
+STUDIO_DIR = PACKAGE_ROOT / "studio"
+
+# asyncio is here because it is filelock's cost, not its own.
+DEFERRED = ("filelock", "asyncio", "zipfile", "tarfile")
+
+
+def _modules_after_importing(statement: str) -> set[str]:
+ probe = (
+ f"{statement}\n"
+ "import json, sys\n"
+ f"print(json.dumps(sorted(m for m in {DEFERRED!r} if m in sys.modules)))\n"
+ )
+ result = subprocess.run(
+ [sys.executable, "-c", probe],
+ capture_output = True,
+ text = True,
+ cwd = str(PACKAGE_ROOT),
+ )
+ assert result.returncode == 0, result.stderr
+ import json
+
+ return set(json.loads(result.stdout.strip().splitlines()[-1]))
+
+
+ "statement",
+ [
+ "import sys; sys.path.insert(0, 'studio'); import prebuilt_core",
+ "import sys; sys.path.insert(0, 'studio'); import install_llama_prebuilt",
+ ],
+ ids = ["prebuilt_core", "install_llama_prebuilt"],
+)
+def test_importing_an_installer_does_not_load_the_download_stack(statement):
+ """A marker read, a health check or a `--help` must not pay for filelock."""
+ assert _modules_after_importing(statement) == set()
+
+
+def test_the_lock_still_uses_filelock_when_it_is_installed():
+ """Deferred, not dropped: the real lock is what makes concurrent installs safe."""
+ sys.path.insert(0, str(STUDIO_DIR))
+ import prebuilt_core
+
+ file_lock, file_lock_timeout = prebuilt_core.filelock_classes()
+ pytest.importorskip("filelock")
+ assert file_lock is not None and file_lock_timeout is not None
+ assert file_lock.__module__.startswith("filelock")
+
+
+def test_a_missing_filelock_still_answers_with_the_pid_fallback(tmp_path, monkeypatch):
+ """The ImportError arm, through install_lock: the point is that it still locks."""
+ sys.path.insert(0, str(STUDIO_DIR))
+ import prebuilt_core
+
+ monkeypatch.setattr(prebuilt_core, "_FILELOCK_CLASSES", (None, None))
+ lock_path = tmp_path / "install.lock"
+ with prebuilt_core.install_lock(lock_path, timeout = 5):
+ # The fallback writes a real file so a crashed holder can be spotted.
+ assert lock_path.is_file()
+ assert not lock_path.exists()
+
+
+def test_the_verdict_is_cached_so_a_missing_filelock_is_not_reimported(monkeypatch):
+ """An ImportError is not cheap to repeat, and install_lock is called per install."""
+ sys.path.insert(0, str(STUDIO_DIR))
+ import prebuilt_core
+
+ monkeypatch.setattr(prebuilt_core, "_FILELOCK_CLASSES", None)
+ monkeypatch.delitem(sys.modules, "filelock", raising = False)
+
+ class CountingBlocker:
+ """Refuses filelock and counts how many times it was asked."""
+
+ def __init__(self):
+ self.calls = 0
+
+ def find_spec(
+ self,
+ name,
+ path = None,
+ target = None,
+ ):
+ if name == "filelock" or name.startswith("filelock."):
+ self.calls += 1
+ raise ImportError("filelock is not installed in this environment")
+ return None
+
+ blocker = CountingBlocker()
+ monkeypatch.setattr(sys, "meta_path", [blocker, *sys.meta_path])
+
+ assert prebuilt_core.filelock_classes() == (None, None)
+ assert prebuilt_core.filelock_classes() == (None, None)
+ # Twice asked, once attempted: the second call read the cache.
+ assert blocker.calls == 1, blocker.calls