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: make the install-time bytecode precompile opt-in (#15923)

Daniel Han867aa46397c8
diff --git a/studio/precompile_bytecode.py b/studio/precompile_bytecode.py
index 01e6f8117d2..f17023998f2 100644
--- a/studio/precompile_bytecode.py
+++ b/studio/precompile_bytecode.py
@@ -5,7 +5,8 @@
Only adds missing .pyc, never rewrites one; always exits 0; prints nothing; skipped under 4 GiB free.
A timeout or Ctrl+C kills the worker tree and removes exactly what this run created.
-Opt out: UV_COMPILE_BYTECODE / UNSLOTH_STUDIO_COMPILE_BYTECODE false. Bound:
+Off by default (a whole-venv compile per update cost more than lazy compile; Defender scans each .pyc).
+Opt in: UNSLOTH_STUDIO_COMPILE_BYTECODE (or UV_COMPILE_BYTECODE) true; a false always wins. Bound:
UNSLOTH_STUDIO_COMPILE_BYTECODE_TIMEOUT (240 s, under the desktop installer's 5 min silence report).
Usage: python -I precompile_bytecode.py [DIR ...]
"""
@@ -18,6 +19,8 @@ import sys
import sysconfig
_FALSE = ("0", "false", "no", "off")
+_TRUE = ("1", "true", "yes", "on")
+_SWITCHES = ("UV_COMPILE_BYTECODE", "UNSLOTH_STUDIO_COMPILE_BYTECODE")
_DEFAULT_TIMEOUT = 240.0
_MIN_FREE_BYTES = 4 * 1024**3
_PACKAGES = ("studio", "unsloth", "unsloth_cli")
@@ -30,10 +33,10 @@ _MAX_WORKERS = 32
def _disabled():
- for name in ("UV_COMPILE_BYTECODE", "UNSLOTH_STUDIO_COMPILE_BYTECODE"):
- if os.environ.get(name, "").strip().lower() in _FALSE:
- return True
- return False
+ values = [os.environ.get(name, "").strip().lower() for name in _SWITCHES]
+ if any(value in _FALSE for value in values):
+ return True
+ return not any(value in _TRUE for value in values)
def _timeout():
diff --git a/studio/setup.ps1 b/studio/setup.ps1
index 34473d988d8..0b6de215d02 100644
--- a/studio/setup.ps1
+++ b/studio/setup.ps1
@@ -10114,12 +10114,14 @@ if (-not $llamaCppIsLink -and (
Complete-FrontendBuildBackground
-# ── Precompile bytecode ── (uv installs without .pyc; only after a dependency pass, never fatal)
+# ── Precompile bytecode ── (opt-in: a whole-venv compile per update cost more than lazy compile on import; never fatal)
$_pycPython = Join-Path $VenvDir 'Scripts\python.exe'
$_pycHelper = Join-Path $PSScriptRoot 'precompile_bytecode.py'
-$_pycOptedOut = @(@($env:UV_COMPILE_BYTECODE, $env:UNSLOTH_STUDIO_COMPILE_BYTECODE) |
- Where-Object { $_ -and (@('0', 'false', 'no', 'off') -contains $_.Trim().ToLowerInvariant()) }).Count -gt 0
-if (($script:SetupVenvChanged -or $env:UNSLOTH_SETUP_RERUN -eq '1') -and -not $_pycOptedOut -and
+$_pycSwitches = @(@($env:UV_COMPILE_BYTECODE, $env:UNSLOTH_STUDIO_COMPILE_BYTECODE) |
+ Where-Object { $_ } | ForEach-Object { $_.Trim().ToLowerInvariant() })
+$_pycOptedOut = @($_pycSwitches | Where-Object { @('0', 'false', 'no', 'off') -contains $_ }).Count -gt 0
+$_pycOptedIn = @($_pycSwitches | Where-Object { @('1', 'true', 'yes', 'on') -contains $_ }).Count -gt 0
+if (($script:SetupVenvChanged -or $env:UNSLOTH_SETUP_RERUN -eq '1') -and $_pycOptedIn -and -not $_pycOptedOut -and
(Test-Path -LiteralPath $_pycPython -PathType Leaf) -and
(Test-Path -LiteralPath $_pycHelper -PathType Leaf)) {
step "python" "precompiling bytecode..."
diff --git a/studio/setup.sh b/studio/setup.sh
index 772a4be3383..351c62ae838 100755
--- a/studio/setup.sh
+++ b/studio/setup.sh
@@ -5489,15 +5489,16 @@ _print_llama_gpu_notes() {
_frontend_bg_join
-# ── Precompile bytecode ── (uv installs without .pyc; only after a dependency pass, never fatal)
+# ── Precompile bytecode ── (opt-in: a whole-venv compile per update cost more than lazy compile on import; never fatal)
_setup_bytecode_opted_out() {
- local _sbo
+ local _sbo _sbo_out=0
for _sbo in "${UV_COMPILE_BYTECODE:-}" "${UNSLOTH_STUDIO_COMPILE_BYTECODE:-}"; do
case "$(printf '%s' "$_sbo" | tr -d '[:space:]' | tr '[:upper:]' '[:lower:]')" in
0|false|no|off) return 0 ;;
+ 1|true|yes|on) _sbo_out=1 ;;
esac
done
- return 1
+ return "$_sbo_out"
}
if { [ "${_SETUP_VENV_CHANGED:-false}" = true ] || [ "${UNSLOTH_SETUP_RERUN:-}" = 1 ]; } \
&& [ "${_COLAB_NO_VENV:-false}" != true ] && [ -x "$VENV_DIR/bin/python" ] \
diff --git a/tests/python/test_installer_compile_bytecode.py b/tests/python/test_installer_compile_bytecode.py
index 58515691305..5264d78f820 100644
--- a/tests/python/test_installer_compile_bytecode.py
+++ b/tests/python/test_installer_compile_bytecode.py
@@ -8,6 +8,9 @@ uv installs without .pyc, so the first launch paid for compiling every module `i
loads. studio/precompile_bytecode.py runs compileall over site-packages (and an editable checkout)
after setup.sh / setup.ps1 changed the venv. uv itself is left alone: no installer sets
UV_COMPILE_BYTECODE, because a uv compile failure or timeout fails the install command (#5983).
+
+Opt-in on every OS (UNSLOTH_STUDIO_COMPILE_BYTECODE=1): a whole-venv compile per update cost more
+than Python's lazy compile on first import.
"""
from __future__ import annotations
@@ -68,6 +71,7 @@ def _clean_env(monkeypatch):
"SOURCE_DATE_EPOCH",
):
monkeypatch.delenv(name, raising = False)
+ monkeypatch.setenv("UNSLOTH_STUDIO_COMPILE_BYTECODE", "1")
def _tree(root: Path) -> Path:
@@ -166,10 +170,13 @@ def _setup_sh_block() -> str:
@pytest.mark.parametrize(
"changed, rerun, opt_out, fake_exit, expect_call",
[
- ("true", "", None, 1, True),
- ("true", "", None, 0, True),
- ("false", "1", None, 1, True),
- ("false", "", None, 0, False),
+ ("true", "", None, 1, False),
+ ("false", "1", None, 1, False),
+ ("true", "", ("UNSLOTH_STUDIO_COMPILE_BYTECODE", "1"), 1, True),
+ ("true", "", ("UNSLOTH_STUDIO_COMPILE_BYTECODE", "1"), 0, True),
+ ("false", "1", ("UNSLOTH_STUDIO_COMPILE_BYTECODE", " On "), 1, True),
+ ("false", "", ("UNSLOTH_STUDIO_COMPILE_BYTECODE", "1"), 0, False),
+ ("true", "", ("UNSLOTH_STUDIO_COMPILE_BYTECODE", "maybe"), 0, False),
("true", "", ("UV_COMPILE_BYTECODE", " FALSE "), 0, False),
("true", "", ("UNSLOTH_STUDIO_COMPILE_BYTECODE", "0"), 0, False),
("true", "", ("UV_COMPILE_BYTECODE", "1"), 0, True),
@@ -215,14 +222,19 @@ def test_setup_sh_block_never_fails_and_runs_only_after_a_deps_pass(
@pytest.mark.skipif(PWSH is None or BASH is None, reason = "needs PowerShell")
@pytest.mark.parametrize(
- "opt_out, expect_call",
+ "switches, expect_call",
[
- (None, True),
- (("UV_COMPILE_BYTECODE", "False"), False),
- (("UNSLOTH_STUDIO_COMPILE_BYTECODE", "off"), False),
+ ({}, False),
+ ({"UNSLOTH_STUDIO_COMPILE_BYTECODE": "1"}, True),
+ ({"UNSLOTH_STUDIO_COMPILE_BYTECODE": " On "}, True),
+ ({"UV_COMPILE_BYTECODE": "true"}, True),
+ ({"UNSLOTH_STUDIO_COMPILE_BYTECODE": "maybe"}, False),
+ ({"UV_COMPILE_BYTECODE": "False"}, False),
+ ({"UNSLOTH_STUDIO_COMPILE_BYTECODE": "off"}, False),
+ ({"UNSLOTH_STUDIO_COMPILE_BYTECODE": "1", "UV_COMPILE_BYTECODE": "0"}, False),
],
)
-def test_setup_ps1_block_never_fails(tmp_path, opt_out, expect_call):
+def test_setup_ps1_block_never_fails(tmp_path, switches, expect_call):
lines = _lines(SETUP_PS1)
start = _index(lines, r"^\$_pycPython = ")
footer = next(i for i, line in enumerate(lines) if line == "# Footer")
@@ -268,8 +280,7 @@ def test_setup_ps1_block_never_fails(tmp_path, opt_out, expect_call):
}
else:
env = {"PATH": "/usr/bin:/bin", "HOME": str(tmp_path)}
- if opt_out:
- env[opt_out[0]] = opt_out[1]
+ env.update(switches)
result = run_pwsh(
[PWSH, "-NoProfile", "-NonInteractive", "-Command", script],
env = env,
@@ -285,6 +296,37 @@ def test_setup_ps1_block_never_fails(tmp_path, opt_out, expect_call):
assert marker.exists() is expect_call
+def test_helper_is_off_by_default(tmp_path, monkeypatch):
+ _clean_env(monkeypatch)
+ monkeypatch.delenv("UNSLOTH_STUDIO_COMPILE_BYTECODE", raising = False)
+ helper = _helper()
+ _tree(tmp_path)
+ before = _snapshot(tmp_path)
+ assert helper.main([str(tmp_path)]) == 0
+ assert _snapshot(tmp_path) == before, "no OS may precompile without the opt-in"
+
+
+ "switches, compiles",
+ [
+ ({"UNSLOTH_STUDIO_COMPILE_BYTECODE": "1"}, True),
+ ({"UNSLOTH_STUDIO_COMPILE_BYTECODE": "TRUE"}, True),
+ ({"UV_COMPILE_BYTECODE": "yes"}, True),
+ ({"UNSLOTH_STUDIO_COMPILE_BYTECODE": ""}, False),
+ ({"UNSLOTH_STUDIO_COMPILE_BYTECODE": "1", "UV_COMPILE_BYTECODE": "0"}, False),
+ ],
+)
+def test_helper_opt_in(tmp_path, monkeypatch, switches, compiles):
+ _clean_env(monkeypatch)
+ monkeypatch.delenv("UNSLOTH_STUDIO_COMPILE_BYTECODE", raising = False)
+ for name, value in switches.items():
+ monkeypatch.setenv(name, value)
+ helper = _helper()
+ pkg = _tree(tmp_path)
+ assert helper.main([str(tmp_path)]) == 0
+ assert len(_pycs(pkg)) == (2 if compiles else 0)
+
+
def test_helper_compiles_a_tree_and_is_idempotent(tmp_path, monkeypatch):
_clean_env(monkeypatch)
pkg = _tree(tmp_path)
@@ -441,7 +483,10 @@ def test_a_stop_signal_kills_the_compile_and_undoes_it(tmp_path, signame):
encoding = "utf-8",
)
proc = subprocess.Popen(
- [sys.executable, str(driver)], stdout = subprocess.PIPE, stderr = subprocess.PIPE
+ [sys.executable, str(driver)],
+ stdout = subprocess.PIPE,
+ stderr = subprocess.PIPE,
+ env = {**os.environ, "UNSLOTH_STUDIO_COMPILE_BYTECODE": "1"},
)
deadline = time.monotonic() + 30
while not pidfile.exists() and time.monotonic() < deadline: