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.

Raise the unsloth_zoo floor to 2026.9.5 now that the compiled-path sentinel fix shipped (#11210)

Daniel Han317b702da803
diff --git a/install.ps1 b/install.ps1
index fec4f357c91..4e189f671f0 100644
--- a/install.ps1
+++ b/install.ps1
@@ -9525,7 +9525,10 @@ exit 0
if ($SkipTorch) {
# No-torch: install unsloth + unsloth-zoo with --no-deps, then
# runtime deps (typer, safetensors, transformers, etc.) with --no-deps.
- $baseInstallExit = Invoke-InstallCommandRetry -Label "install unsloth (migrated no-torch)" { & $script:UvExe pip install --python $VenvPython --no-deps --reinstall-package unsloth --reinstall-package unsloth-zoo "$_unslothReleaseInstallSpec" "unsloth-zoo>=2026.9.3" }
+ # --no-deps means unsloth's own metadata is never read, so this spec IS the zoo
+ # floor for this path. Keep it equal to the unsloth_zoo floor in pyproject.toml
+ # (tests/test_installer_zoo_floor_parity.py enforces that).
+ $baseInstallExit = Invoke-InstallCommandRetry -Label "install unsloth (migrated no-torch)" { & $script:UvExe pip install --python $VenvPython --no-deps --reinstall-package unsloth --reinstall-package unsloth-zoo "$_unslothReleaseInstallSpec" "unsloth-zoo>=2026.9.5" }
if ($baseInstallExit -eq 0) {
# Resolve pydantic WITH deps so pip pins pydantic-core
# to the matching version (no-torch-runtime.txt below
@@ -9795,7 +9798,8 @@ exit 0
if ($SkipTorch) {
# No-torch: install unsloth + unsloth-zoo with --no-deps, then
# runtime deps (typer, safetensors, transformers, etc.) with --no-deps.
- $baseInstallExit = Invoke-InstallCommandRetry -Label "install unsloth (no-torch)" { & $script:UvExe pip install --python $VenvPython --no-deps --upgrade-package unsloth --upgrade-package unsloth-zoo "$_unslothReleaseInstallSpec" "unsloth-zoo>=2026.9.3" }
+ # --no-deps: this spec IS the zoo floor here. Kept equal to pyproject.toml's.
+ $baseInstallExit = Invoke-InstallCommandRetry -Label "install unsloth (no-torch)" { & $script:UvExe pip install --python $VenvPython --no-deps --upgrade-package unsloth --upgrade-package unsloth-zoo "$_unslothReleaseInstallSpec" "unsloth-zoo>=2026.9.5" }
if ($baseInstallExit -eq 0) {
# Same pydantic-with-deps trick as the migrated branch.
$baseInstallExit = Invoke-InstallCommandRetry -Label "install pydantic" { & $script:UvExe pip install --python $VenvPython pydantic }
diff --git a/install.sh b/install.sh
index 5a4f19a3fdd..7b32eb533c9 100755
--- a/install.sh
+++ b/install.sh
@@ -5787,9 +5787,12 @@ if [ "$_MIGRATED" = true ]; then
substep "upgrading unsloth in migrated environment..."
if [ "$SKIP_TORCH" = true ]; then
# No-torch: --no-deps throughout (PyPI metadata still hard-deps torch).
+ # --no-deps means unsloth's own metadata is never read, so this spec IS the zoo floor
+ # for this path. Keep it equal to the unsloth_zoo floor in pyproject.toml
+ # (tests/test_installer_zoo_floor_parity.py enforces that).
run_install_cmd_retry "install unsloth (migrated no-torch)" uv pip install --python "$_VENV_PY" --no-deps \
--reinstall-package unsloth --reinstall-package unsloth-zoo \
- "$_unsloth_release_install_spec" "unsloth-zoo>=2026.9.3"
+ "$_unsloth_release_install_spec" "unsloth-zoo>=2026.9.5"
# Resolve pydantic WITH deps so pip pins pydantic-core to the
# matching version (no-torch-runtime.txt below is --no-deps).
# All transitive deps are torch-free.
@@ -6009,9 +6012,10 @@ elif [ -n "$TORCH_INDEX_URL" ]; then
substep "installing unsloth (this may take a few minutes)..."
_build_unsloth_torch_overrides
if [ "$SKIP_TORCH" = true ]; then
+ # --no-deps: this spec IS the zoo floor here. Kept equal to pyproject.toml's.
run_install_cmd_retry "install unsloth (no-torch)" uv pip install --python "$_VENV_PY" --no-deps \
--upgrade-package unsloth --upgrade-package unsloth-zoo \
- "$_unsloth_release_install_spec" "unsloth-zoo>=2026.9.3"
+ "$_unsloth_release_install_spec" "unsloth-zoo>=2026.9.5"
# Same pydantic-with-deps trick as the migrated branch.
run_install_cmd_retry "install pydantic (with deps for compatible core)" \
uv pip install --python "$_VENV_PY" pydantic
diff --git a/pyproject.toml b/pyproject.toml
index 93c78833e9e..729faf125bc 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -201,16 +201,20 @@ triton = [
huggingfacenotorch = [
# unsloth_zoo.compiler embeds its own copy of the empty-logits sentinel in the code it
- # generates for the compiled trainers, so fixing _utils.py here does not reach the
- # compiled path while an older zoo is resolvable: 2026.9.4, the newest on PyPI, still
- # hands FSDP2 mixed precision a sentinel that answers `__dataclass_fields__` and dies in
- # `dataclasses.replace`. The release carrying the matching fix
- # (unslothai/unsloth-zoo#1259) is not published yet, and a floor no release satisfies
- # makes the package uninstallable, so the floor stays at 2026.9.4 for now and the
- # eager-path fix below stands on its own. Raise the floor once #1259 ships; the
- # compiled-path probes in tests/test_empty_logits_compiled_path_probes.py gate on the
- # INSTALLED zoo, not on this pin, so they start running on their own.
- "unsloth_zoo>=2026.9.4",
+ # generates for the compiled trainers, so fixing _utils.py here never reached the compiled
+ # path while an older zoo stayed resolvable: 2026.9.4 hands FSDP2 mixed precision a
+ # sentinel that answers `__dataclass_fields__` and then dies in `dataclasses.replace`.
+ # 2026.9.5 carries the matching fix (unslothai/unsloth-zoo#1259), so the floor moves to it
+ # and the compiled path is covered for the first time rather than resting on the eager
+ # fix alone. The compiled-path probes in tests/test_empty_logits_compiled_path_probes.py
+ # gate on the INSTALLED zoo rather than on this pin, so they start running by themselves
+ # wherever 2026.9.5 or newer is the zoo actually present.
+ #
+ # This does NOT lift the transformers ceiling below. 2026.9.5 still declares
+ # `transformers<=5.5.0` in its own metadata, so the resolver intersects our transformers
+ # range down to 5.5.0 whatever this file says. That one waits on
+ # unslothai/unsloth-zoo#1227 and a later zoo release.
+ "unsloth_zoo>=2026.9.5",
"wheel>=0.42.0",
"packaging",
"numpy",
@@ -276,7 +280,7 @@ audio-torch280 = [
]
huggingface = [
"unsloth[huggingfacenotorch]",
- "unsloth_zoo>=2026.9.4",
+ "unsloth_zoo>=2026.9.5",
"torchvision",
"unsloth[triton]",
]
@@ -895,7 +899,7 @@ colab-ampere-torch220 = [
"flash-attn>=2.6.3 ; ('linux' in sys_platform)",
]
colab-new = [
- "unsloth_zoo>=2026.9.4",
+ "unsloth_zoo>=2026.9.5",
"packaging",
"tyro",
"transformers>=4.51.3,!=4.52.0,!=4.52.1,!=4.52.2,!=4.52.3,!=4.53.0,!=4.54.0,!=4.55.0,!=4.55.1,!=4.57.0,!=4.57.4,!=4.57.5,!=5.0.0,!=5.1.0,<=5.5.0",
diff --git a/tests/test_empty_logits_compiled_path_probes.py b/tests/test_empty_logits_compiled_path_probes.py
index c2a35512af6..cfb77cf6537 100644
--- a/tests/test_empty_logits_compiled_path_probes.py
+++ b/tests/test_empty_logits_compiled_path_probes.py
@@ -53,19 +53,19 @@ class EmptyLogits:
"""
-# The first unsloth_zoo release expected to generate a fixed sentinel, i.e. the one that
-# carries unslothai/unsloth-zoo#1259. Not yet published: 2026.9.4 is the newest on PyPI.
+# The first unsloth_zoo release that generates a fixed sentinel, i.e. the one that carries
+# unslothai/unsloth-zoo#1259. Published, and pyproject.toml's floor now names it too.
#
# This deliberately does NOT read the `unsloth_zoo>=` floor out of pyproject.toml, which is
-# what it used to do. That coupling was only correct while the pin and the fix named the
-# same release. The pin is now held at 2026.9.4 because a floor no release satisfies makes
-# unsloth uninstallable, and 2026.9.4 is exactly the zoo that still generates the BROKEN
-# sentinel -- so a gate reading the pin would let these probes run against a zoo that has
-# the bug, and they would fail on a correct tree. What the probes assert is a property of
+# what it used to do. The two agree again today, but the coupling is only ever correct while
+# the pin and the fix name the same release, and they came apart once already: the pin sat at
+# 2026.9.4 for as long as #1259 was unpublished, and 2026.9.4 is exactly the zoo that still
+# generates the BROKEN sentinel, so a gate reading the pin would have run these probes against
+# a zoo carrying the bug and failed on a correct tree. What the probes assert is a property of
# the INSTALLED zoo, so the gate names the release that fixes it, directly.
#
-# Until that release exists, every probe below skips and the always-on canary at the bottom
-# of this file is what keeps the assertions honest. Move this constant when #1259 ships.
+# Where an older zoo is what is actually installed, every probe below skips and the always-on
+# canary at the bottom of this file is what keeps the assertions honest.
ZOO_RELEASE_WITH_GENERATED_SENTINEL_FIX = Version("2026.9.5")
@@ -116,9 +116,9 @@ def generated_sentinel():
pytest.skip(
f"installed unsloth_zoo {installed} still generates the pre-fix sentinel; it is "
f"fixed from {ZOO_RELEASE_WITH_GENERATED_SENTINEL_FIX} "
- f"(unslothai/unsloth-zoo#1259) onwards, which is not published yet. The "
- f"canary test in this file runs unconditionally and shows these probes have "
- f"teeth."
+ f"(unslothai/unsloth-zoo#1259) onwards, which pyproject.toml's floor now "
+ f"requires, so upgrade unsloth_zoo here to run these. The canary test in this "
+ f"file runs unconditionally and shows these probes have teeth."
)
return _build(_generated_sentinel_source(compiler))
diff --git a/tests/test_installer_zoo_floor_parity.py b/tests/test_installer_zoo_floor_parity.py
new file mode 100644
index 00000000000..44cc3e1df77
--- /dev/null
+++ b/tests/test_installer_zoo_floor_parity.py
@@ -0,0 +1,148 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+"""The installer's `--no-deps` unsloth-zoo specs are a floor in their own right, so they must
+match pyproject.toml's.
+
+`uv pip install --no-deps` never reads unsloth's metadata, so on those paths the
+`unsloth-zoo>=...` written on the command line is the ONLY thing deciding which zoo the user
+ends up with. When pyproject.toml moves and the installers do not, a no-torch install happily
+resolves a zoo that pyproject.toml already rejects, and the defect the floor was raised for is
+still shipped. That is not hypothetical: main carried `unsloth-zoo>=2026.9.3` in the
+installers while pyproject.toml said `>=2026.9.4`.
+
+The with-deps sites are deliberately NOT checked. There the resolver intersects the
+command-line spec with unsloth's own metadata, so pyproject.toml is already the binding floor
+and a lower spec on the command line changes nothing.
+
+Reads files only, so this runs on the Windows and macOS runners too.
+"""
+
+from __future__ import annotations
+
+import re
+import tomllib
+from pathlib import Path
+
+import pytest
+from packaging.requirements import InvalidRequirement, Requirement
+from packaging.version import Version
+
+
+REPO = Path(__file__).resolve().parents[1]
+PYPROJECT = REPO / "pyproject.toml"
+INSTALL_SH = REPO / "install.sh"
+INSTALL_PS1 = REPO / "install.ps1"
+
+# Every `--no-deps` site that names a zoo floor, one per installer branch:
+# install.sh migrated + SKIP_TORCH, fresh + SKIP_TORCH
+# install.ps1 migrated + SkipTorch, fresh + SkipTorch
+# Pinned so that adding a fifth without thinking about the floor fails here rather than
+# shipping a path nothing checks.
+EXPECTED_NO_DEPS_SITES = 4
+
+_ZOO_SPEC = re.compile(r"""unsloth[-_]zoo\s*(?:>=|==)\s*[0-9][^"'\s]*""")
+
+
+def _logical_lines(path: Path) -> list[tuple[int, str]]:
+ """Join shell backslash continuations so one command is one string."""
+ out: list[tuple[int, str]] = []
+ buffer = ""
+ start = 0
+ for number, raw in enumerate(path.read_text(encoding = "utf-8").splitlines(), start = 1):
+ if not buffer:
+ start = number
+ stripped = raw.rstrip()
+ if stripped.endswith("\\"):
+ buffer += stripped[:-1] + " "
+ continue
+ buffer += stripped
+ out.append((start, buffer))
+ buffer = ""
+ if buffer:
+ out.append((start, buffer))
+ return out
+
+
+def _pyproject_floor() -> Version:
+ data = tomllib.loads(PYPROJECT.read_text(encoding = "utf-8"))
+ project = data.get("project") or {}
+ raws: list[str] = list(project.get("dependencies") or [])
+ for extra in (project.get("optional-dependencies") or {}).values():
+ raws.extend(extra)
+ floors: dict[str, Version] = {}
+ for raw in raws:
+ try:
+ req = Requirement(raw)
+ except InvalidRequirement:
+ continue
+ if req.name.lower().replace("_", "-") != "unsloth-zoo":
+ continue
+ lower = [
+ Version(str(spec.version))
+ for spec in req.specifier
+ if spec.operator in (">=", "==", "~=")
+ ]
+ if lower:
+ floors[raw] = max(lower)
+ assert floors, "pyproject.toml declares no versioned unsloth_zoo requirement at all"
+ assert len(set(floors.values())) == 1, (
+ f"pyproject.toml declares more than one unsloth_zoo floor: "
+ f"{ {raw: str(v) for raw, v in floors.items()} }. One of them is the one users "
+ f"actually resolve, and which one depends on the extra they picked."
+ )
+ return next(iter(floors.values()))
+
+
+def _installer_sites() -> list[tuple[str, int, str, bool]]:
+ """(file, line, spec, is_no_deps) for every zoo version spec on an install command line."""
+ sites: list[tuple[str, int, str, bool]] = []
+ for path in (INSTALL_SH, INSTALL_PS1):
+ lines = (
+ _logical_lines(path)
+ if path.suffix == ".sh"
+ else list(enumerate(path.read_text(encoding = "utf-8").splitlines(), start = 1))
+ )
+ for number, text in lines:
+ if "pip install" not in text:
+ continue
+ no_deps = "--no-deps" in text
+ for spec in _ZOO_SPEC.findall(text):
+ sites.append((path.name, number, spec, no_deps))
+ return sites
+
+
+def test_the_no_deps_installer_sites_carry_the_pyproject_floor() -> None:
+ floor = _pyproject_floor()
+ sites = [site for site in _installer_sites() if site[3]]
+ assert sites, (
+ "found no --no-deps unsloth-zoo spec in either installer. Either the no-torch paths "
+ "were reworked, in which case retune this test, or the floor they carried was "
+ "dropped, in which case those installs resolve any zoo at all."
+ )
+ assert len(sites) == EXPECTED_NO_DEPS_SITES, (
+ f"expected {EXPECTED_NO_DEPS_SITES} --no-deps zoo floors, found {len(sites)}: "
+ f"{[(f, n, s) for f, n, s, _ in sites]}. A new one needs the floor too, since "
+ f"--no-deps means the command line is all the resolver sees."
+ )
+ stale = [
+ (name, number, spec)
+ for name, number, spec, _ in sites
+ if Version(spec.split(">=")[-1].split("==")[-1]) < floor
+ ]
+ assert not stale, (
+ f"these --no-deps installer sites still accept an unsloth_zoo older than the "
+ f"pyproject.toml floor {floor}: {stale}. --no-deps ignores package metadata, so such "
+ f"an install resolves a zoo pyproject.toml already rejects."
+ )
+
+
+def test_every_installer_zoo_spec_is_a_real_version() -> None:
+ """A typo'd spec would silently become a name-only requirement and pin nothing."""
+ sites = _installer_sites()
+ assert sites, "no unsloth-zoo version spec found in the installers at all"
+ for name, number, spec, _ in sites:
+ try:
+ Requirement(spec)
+ except InvalidRequirement as error: # pragma: no cover - only on a malformed spec
+ pytest.fail(f"{name}:{number} has an unparseable zoo spec {spec!r}: {error}")