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.

Add the Qwen-Image-2.1 family, and the Diffusers it needs by default (#11405)

Daniel Hanc121e804081e
diff --git a/scripts/build_prequant_checkpoint.py b/scripts/build_prequant_checkpoint.py
index 83b919e436c..b0e203b91a0 100644
--- a/scripts/build_prequant_checkpoint.py
+++ b/scripts/build_prequant_checkpoint.py
@@ -135,6 +135,12 @@ def main(argv = None) -> int:
"--base", required = True, help = "diffusers base repo (carries the transformer subfolder)"
)
p.add_argument("--family", required = True, help = "diffusion family name/alias (e.g. z-image)")
+ p.add_argument(
+ "--base-model-id",
+ default = None,
+ help = "the base id to RECORD in the checkpoint, when --base is a local mirror whose "
+ "directory name differs from the Hub repo. Must still name this family's base model.",
+ )
p.add_argument("--scheme", required = True, help = "quant scheme: int8 | fp8 | nvfp4 | mxfp8")
p.add_argument(
"--out",
@@ -197,6 +203,26 @@ def main(argv = None) -> int:
if fam is None:
print(f"error: unknown family '{args.family}'", flush = True)
return 2
+ # What the artifact RECORDS as its base, which is not always what this build READ. Weights staged into a local
+ # directory keep that directory's name, and the loader's ``_same_base_model`` compares final path segments: a
+ # checkpoint built from ./temp/qwen_image_21 records a base whose tail is "qwen_image_21", the load asks for
+ # "Qwen/Qwen-Image-2.1", the tails differ and a perfectly good artifact is refused after the dense shards were
+ # already dropped. Pinned to the FAMILY's own base_repo rather than taken on trust, so the override can only ever
+ # name the model this family is for, and cannot relabel one checkpoint as another.
+ recorded_base = args.base_model_id or args.base
+ if args.base_model_id:
+ # EXACT, not the loader's ``_same_base_model``. That helper compares final path segments on
+ # purpose, so a checkpoint built from ./temp/qwen_image_21 still matches Qwen/Qwen-Image-2.1;
+ # borrowing it here would also accept ``other/Qwen-Image-2.1``, record the artifact under that
+ # namespace, and have the loader's equally tolerant comparison wave it through as the official
+ # base. What gets WRITTEN into a published file has to be the canonical id itself.
+ if recorded_base.strip() != fam.base_repo:
+ print(
+ f"error: --base-model-id {recorded_base!r} is not {fam.name}'s base "
+ f"({fam.base_repo!r}); it would label this checkpoint as a different model",
+ flush = True,
+ )
+ return 2
transformer_cls = getattr(diffusers, fam.transformer_class)
# The CONTAINER is chosen by the --out extension, so one flag picks the on-disk format, the reachable upload name
# and the writer, and they cannot be set to disagree.
@@ -299,7 +325,7 @@ def main(argv = None) -> int:
for k, v in transformer.state_dict().items()
}
metadata = {
- "base_model_id": args.base,
+ "base_model_id": recorded_base,
"family": fam.name,
"scheme": scheme,
"min_features": args.min_features,
diff --git a/studio/backend/core/inference/diffusion.py b/studio/backend/core/inference/diffusion.py
index 2631f02d4e7..19a09ca0823 100644
--- a/studio/backend/core/inference/diffusion.py
+++ b/studio/backend/core/inference/diffusion.py
@@ -640,6 +640,11 @@ _TRUSTED_NON_GGUF_REPOS = frozenset(
"qwen/qwen-image",
"qwen/qwen-image-2512",
"qwen/qwen-image-edit-2511",
+ # Qwen-Image-2.1: the family's own base_repo, and a family whose base is not listed here is
+ # not a family at all. Detection resolves it, the version gate passes once the pinned main
+ # build is in, and then validate_load_request refuses it as a non-unsloth repo before the
+ # pipeline is ever built.
+ "qwen/qwen-image-2.1",
# Krea 2: assembled per-component. Turbo = inference; Raw = the LoRA training base.
"krea/krea-2-turbo",
"krea/krea-2-raw",
diff --git a/studio/backend/core/inference/diffusion_auto_policy.py b/studio/backend/core/inference/diffusion_auto_policy.py
index 81060a9d237..afc232cb2a5 100644
--- a/studio/backend/core/inference/diffusion_auto_policy.py
+++ b/studio/backend/core/inference/diffusion_auto_policy.py
@@ -47,6 +47,11 @@ _FAMILY_BF16_GB: dict[str, tuple[float, float, float]] = {
"flux.2-dev": (64.5, 48.0, 0.4),
"qwen-image": (40.9, 16.6, 0.3),
"qwen-image-edit": (40.9, 16.6, 0.3),
+ # A different architecture, not a refreshed Qwen-Image: 32 single-stream blocks against 60
+ # dual-stream ones, so the DiT is 14.2 GB rather than 40.9, while the Qwen3-VL 8B encoder is
+ # LARGER than Qwen-Image's Qwen2.5-VL 7B. Ships bf16, so resident equals on-disk. Read off the
+ # Hub sibling metadata for Qwen/Qwen-Image-2.1: transformer 14.23, text_encoder 17.53, vae 1.35.
+ "qwen-image-2.1": (14.2, 17.5, 1.4),
"z-image": (12.3, 8.0, 0.2),
"krea-2": (26.3, 8.9, 0.5),
# Ships fp32 (10.4 + 10.5 + 0.3 GB of shards); bf16-resident is half.
diff --git a/studio/backend/core/inference/diffusion_families.py b/studio/backend/core/inference/diffusion_families.py
index 647245b7e98..69e4bda6267 100644
--- a/studio/backend/core/inference/diffusion_families.py
+++ b/studio/backend/core/inference/diffusion_families.py
@@ -340,6 +340,42 @@ _FAMILIES: tuple[DiffusionFamily, ...] = (
sd_cpp_sampling_method = "euler",
sd_cpp_flow_shift = 3.0,
),
+ DiffusionFamily(
+ # Qwen-Image-2.1 is a different ARCHITECTURE, not a refreshed checkpoint, so it is its own
+ # family rather than a prequant_variant_repos row on qwen-image: 32 single-stream blocks
+ # against 60 dual-stream MMDiT ones, nine weights per block, no bias tensors anywhere, one
+ # global modulation projection, a Qwen3-VL text encoder and its own VAE class. Sharing the
+ # qwen-image entry would hand it that family's pipeline, transformer, VAE and exclusion
+ # rules, none of which fit.
+ name = "qwen-image-2.1",
+ pipeline_class = "QwenImage21Pipeline",
+ transformer_class = "QwenImage21Transformer2DModel",
+ base_repo = "Qwen/Qwen-Image-2.1",
+ prequant_repos = (
+ ("int8", "unsloth/Qwen-Image-2.1-FP8"),
+ ("fp8", "unsloth/Qwen-Image-2.1-FP8"),
+ ),
+ # The artifacts are safetensors, not the historical torch.save pickle, so the family has to
+ # NAME them: every derived fallback ends in .pt, and without these rows the loader would ask
+ # the Hub for a file that is not there and silently fall back to the dense bf16 download.
+ prequant_filenames = (
+ ("fp8", "Qwen-Image-2.1-FP8.safetensors"),
+ ("int8", "Qwen-Image-2.1-INT8.safetensors"),
+ ),
+ # Qwen3-VL 8B, pre-cast. Independent of the DiT scheme, as on every other family.
+ te_prequant_repos = (("fp8", "text_encoder", "unsloth/Qwen-Image-2.1-FP8"),),
+ cfg_kwarg = "true_cfg_scale",
+ # 2.1 is UNIFIED: one pipeline, and QwenImage21Pipeline.__call__ takes ``image`` as condition
+ # images alongside the prompt, so this is the FLUX.2 shape rather than the Qwen-Image-Edit
+ # one. Not ``edit``, which means the pipeline IS the edit pipeline and there is no plain
+ # text-to-image: here text-to-image is the default and the images are optional context. The
+ # encoder reads each one as vision context and the VAE turns it into latent tokens prepended
+ # to the noise, with no ``strength`` anywhere, which is exactly what the reference workflow
+ # passes. Without this flag diffusion.py refuses reference images for this family and the
+ # capability ships dark.
+ reference = True,
+ aliases = ("qwen_image_21", "qwenimage21", "qwen-image-21"),
+ ),
DiffusionFamily(
name = "z-image",
pipeline_class = "ZImagePipeline",
@@ -1127,6 +1163,10 @@ _PIPELINE_MIN_DIFFUSERS: dict[str, str] = {
"LTX2Pipeline": "0.37.0",
"Flux2KleinInpaintPipeline": "0.38.0",
"Ideogram4Pipeline": "0.39.0",
+ # Qwen-Image-2.1 merged upstream on 2026-09-18, four weeks after 0.40.0 was cut, so 0.41.0 is
+ # the first release that can carry it. ``_version_tuple`` stops at the first non-numeric part,
+ # so a 0.41.0.dev0 build from main reads as (0, 41, 0) and satisfies this too.
+ "QwenImage21Pipeline": "0.41.0",
"Krea2Pipeline": "0.39.0",
# Older than the 0.35 baseline, but listed anyway: the packaging leaves an UNCONSTRAINED diffusers installable
# below 3.10, so an already-present ancient one satisfies the pin, and quoting the 0.39 floor at a family that has
@@ -1170,6 +1210,14 @@ def pipeline_class_requirement(pipeline_class: str) -> tuple[Optional[str], bool
return minimum, _version_tuple(minimum) >= _version_tuple(_DIFFUSERS_DROPPED_PY39)
+# Minimums that name a release which does not EXIST yet. ``pip install -U 'diffusers>=0.41.0'`` has
+# no candidate today, so quoting it as the remedy sends someone to a command that cannot succeed.
+# Studio installs the pinned main build for exactly these classes (studio/backend/requirements/
+# diffusers-main.txt), so the remedy is to put that back, not to chase a release. Delete an entry
+# here the moment its version ships, which is the same moment diffusers-pin.txt moves to it.
+_UNRELEASED_MIN_DIFFUSERS = frozenset({"0.41.0"})
+
+
def _too_old_message(pipeline_class: str, family_name: str, installed: str) -> str:
"""The refusal text: what is missing, what is installed, and a remedy this interpreter can
actually carry out."""
@@ -1179,6 +1227,14 @@ def _too_old_message(pipeline_class: str, family_name: str, installed: str) -> s
f"'{family_name}' needs a newer diffusers ({pipeline_class}); this environment has "
f"diffusers {installed}. Upgrade with: pip install -U diffusers."
)
+ if minimum in _UNRELEASED_MIN_DIFFUSERS:
+ return (
+ f"'{family_name}' needs diffusers >= {minimum} ({pipeline_class}), which has not been "
+ f"released yet; this environment has diffusers {installed}. Unsloth installs a pinned "
+ "build of diffusers main for this, so re-run the Unsloth installer (and leave "
+ "UNSLOTH_DIFFUSERS_MAIN unset), or install it directly with: pip install -r "
+ "studio/backend/requirements/diffusers-main.txt"
+ )
remedy = f"Upgrade with: pip install -U 'diffusers>={minimum}'."
if needs_py310:
remedy += (
diff --git a/studio/backend/core/inference/diffusion_transformer_quant.py b/studio/backend/core/inference/diffusion_transformer_quant.py
index 934bb8677d5..a68ebeb6fe1 100644
--- a/studio/backend/core/inference/diffusion_transformer_quant.py
+++ b/studio/backend/core/inference/diffusion_transformer_quant.py
@@ -124,6 +124,13 @@ _LTX2_INT8_EXCLUDES = ("audio", "av_cross_attn", "adaln")
_INT8_FAMILY_EXCLUDE_NAME_TOKENS: dict[str, tuple[str, ...]] = {
"qwen-image": _QWENIMAGE_INT8_EXCLUDES,
"qwen-image-edit": _QWENIMAGE_INT8_EXCLUDES, # same DiT class + unpadded text stream
+ # 2.1 is a 32-block SINGLE-stream DiT: no add_* projections, no txt_mlp, so the 20B MMDiT's
+ # exclusion list does not apply and this one was measured rather than inherited. ``txt_in`` is
+ # here as a QUALITY lever, not the small-M crash guard it is on qwen-image: all four policy arms
+ # rendered a deliberately 2-token prompt without tripping ``_int_mm``'s M floor, so nothing
+ # crashes either way. Excluding it scored LPIPS 0.0642 against 0.1032 with the generic tokens
+ # alone, paired over 16 calibration prompts, -0.0390 CI95 [-0.0708, -0.0072], better on 14/16.
+ "qwen-image-2.1": ("txt_in",),
"hunyuanvideo-1.5": _HUNYUAN15_INT8_EXCLUDES,
"hunyuanvideo-1.5-720p": _HUNYUAN15_INT8_EXCLUDES,
"minimax-h3": _MINIMAX_H3_INT8_EXCLUDES,
diff --git a/studio/backend/requirements/diffusers-main.txt b/studio/backend/requirements/diffusers-main.txt
new file mode 100644
index 00000000000..b947e58ab7e
--- /dev/null
+++ b/studio/backend/requirements/diffusers-main.txt
@@ -0,0 +1,29 @@
+# INSTALLED BY DEFAULT, on top of diffusers-pin.txt. Set UNSLOTH_DIFFUSERS_MAIN=0 to opt out.
+#
+# A pinned commit of Diffusers main, for models whose support has merged upstream but has not
+# reached a release yet. Today that is Qwen-Image-2.1: it merged on 2026-09-18, four weeks after
+# 0.40.0 was cut, so 0.41.0 is the first release that can carry it and there is nothing on PyPI
+# that works. Without this file the only way to run it is to break the release pin by hand.
+#
+# Why this is a SEPARATE file rather than an edit to diffusers-pin.txt, even though both now run on
+# every install. That file is the single source of truth for the release everything is built
+# against, and it deliberately refuses a source build. Keeping them apart is what makes this one
+# survivable: the release lands first and stays resident, so a host with no git, no route to
+# github.com, or an upstream that is down for the afternoon keeps a working Studio and loses one
+# model, instead of failing the install outright. Folding the commit into the pin would make a
+# reachable github.com a hard requirement of installing Unsloth at all.
+#
+# Why a COMMIT and not a branch. Nothing in Unsloth can tell two builds of main apart: a git
+# checkout reports 0.41.0.dev0 whatever it was built from, and ``_version_tuple`` truncates that to
+# (0, 41, 0), so the family version gate reads any main build as satisfying 0.41.0. The commit is
+# therefore the only thing actually pinning behaviour, and with this on by default that matters
+# more, not less: everyone gets the same tree. It is also cheaper to check: for a full SHA
+# ``_direct_reference_is_installed`` compares what is recorded in direct_url.json and needs no
+# network, while a branch ref costs a git ls-remote on every pass.
+#
+# This exact commit is the tree the Qwen-Image-2.1 FP8 and INT8 artifacts were built and measured
+# against, so what a user gets is what was tested, not "whatever main was that day".
+#
+# Retiring this file: once 0.41.0 ships, bump diffusers-pin.txt to it and delete this. The family
+# entry already records 0.41.0 as QwenImage21Pipeline's minimum, so nothing else has to move.
+diffusers @ git+https://github.com/huggingface/diffusers.git@80c7ed262aeffbeb43ef13ae04baeb9b84515a69
diff --git a/studio/backend/tests/test_build_prequant_checkpoint.py b/studio/backend/tests/test_build_prequant_checkpoint.py
index a216f5e4904..0467e7d9c2a 100644
--- a/studio/backend/tests/test_build_prequant_checkpoint.py
+++ b/studio/backend/tests/test_build_prequant_checkpoint.py
@@ -204,3 +204,44 @@ def test_a_plain_safetensors_build_derives_the_name_the_loader_now_asks_for_firs
# No upload repo means nothing to derive from, so it refuses rather than guessing.
with pytest.raises(ValueError, match = "prequant_filenames"):
build.upload_destination(zimage, "fp8", rotated = False, safetensors = True)
+
+
+def test_the_recorded_base_must_be_the_canonical_id_not_just_the_same_tail(capsys, monkeypatch):
+ """``--base-model-id`` decides what a PUBLISHED file claims to be, so the loader's deliberately
+ tail-tolerant comparison is the wrong gate here: ``other/Qwen-Image-2.1`` passes it, and the
+ loader's equally tolerant check then accepts those weights as the official family base.
+
+ Driven through ``main`` so the refusal is the one a builder would actually hit, and it has to
+ land BEFORE the download: nothing below is stubbed, so reaching the load would fail differently.
+ """
+ build = _script()
+ fam = detect_family("Qwen/Qwen-Image-2.1")
+ assert fam is not None and fam.base_repo == "Qwen/Qwen-Image-2.1"
+
+ argv = [
+ "--base",
+ "./temp/qwen_image_21",
+ "--family",
+ "qwen-image-2.1",
+ "--scheme",
+ "int8",
+ "--out",
+ "/nonexistent/out.pt",
+ "--base-model-id",
+ "other/Qwen-Image-2.1",
+ ]
+ assert build.main(argv) == 2
+ message = capsys.readouterr().out
+ assert "other/Qwen-Image-2.1" in message and "Qwen/Qwen-Image-2.1" in message
+
+ # The canonical id is accepted, and whitespace around it is not a different model. "Accepted"
+ # here means the run gets PAST this guard: what it reaches next is the transformer class lookup,
+ # which on a diffusers predating the family raises rather than returning 2, and either way it is
+ # no longer this refusal.
+ for accepted in ("Qwen/Qwen-Image-2.1", " Qwen/Qwen-Image-2.1 "):
+ try:
+ rc = build.main(argv[:-1] + [accepted])
+ except AttributeError as exc:
+ assert fam.transformer_class in str(exc), exc
+ continue
+ assert rc != 2 or "is not" not in capsys.readouterr().out, accepted
diff --git a/studio/backend/tests/test_diffusion_auto_policy.py b/studio/backend/tests/test_diffusion_auto_policy.py
index 765fb191a76..cdc1c2f0c36 100644
--- a/studio/backend/tests/test_diffusion_auto_policy.py
+++ b/studio/backend/tests/test_diffusion_auto_policy.py
@@ -521,3 +521,47 @@ def test_the_refusal_only_offers_auto_where_auto_exists():
)
assert "Auto" not in te
assert te.endswith("Leave it unset to keep the dense bf16 encoder.")
+
+
+def test_every_family_with_a_hosted_prequant_can_be_sized():
+ """A family the size table does not know cannot use its own hosted checkpoints.
+
+ ``resolve_dense_quant_candidate`` returns None without a size entry, so
+ ``_pipeline_planned_denoiser_scheme`` has nothing to seed from and the loader keeps the dense
+ transformer, which is precisely the download the prequant rows exist to avoid. The family
+ looks complete from its own entry, so the miss is only visible from here.
+ """
+ from core.inference.diffusion_auto_policy import _FAMILY_BF16_GB
+ from core.inference.diffusion_families import _FAMILIES
+
+ unsizable = [
+ f.name
+ for f in _FAMILIES
+ if (getattr(f, "prequant_repos", ()) or ()) and f.name not in _FAMILY_BF16_GB
+ ]
+ assert not unsizable, (
+ f"these families declare hosted pre-quant checkpoints the auto policy cannot size, so "
+ f"the seed is never chosen and the dense transformer is downloaded instead: {unsizable}"
+ )
+
+
+def test_qwen_image_21_sizes_a_dense_quant_candidate():
+ """The concrete case, with the numbers, so a wrong entry is as visible as a missing one."""
+ from core.inference.diffusion_auto_policy import _FAMILY_BF16_GB, estimate_dense_quant
+ from core.inference.diffusion_families import detect_family
+
+ fam = detect_family("Qwen/Qwen-Image-2.1")
+ transformer, encoders, vae = _FAMILY_BF16_GB[fam.name]
+ # From Qwen/Qwen-Image-2.1's own sibling metadata: 14.23 / 17.53 / 1.35 GB, bf16 on disk.
+ assert 13.5 < transformer < 15.0, transformer
+ assert 17.0 < encoders < 18.0, encoders
+ assert 1.0 < vae < 2.0, vae
+ # And it is NOT Qwen-Image's row: a different architecture, with a smaller DiT and a larger
+ # encoder, so copying that entry would misplan in both directions at once.
+ assert (transformer, encoders, vae) != _FAMILY_BF16_GB["qwen-image"]
+ assert transformer < _FAMILY_BF16_GB["qwen-image"][0]
+ assert encoders > _FAMILY_BF16_GB["qwen-image"][1]
+
+ est = estimate_dense_quant(fam, "fp8", base_repo = fam.base_repo, prequant_available = True)
+ assert est is not None, "no estimate means the pipeline seed is never chosen"
+ assert est.prequant and est.steady_transformer_mib > 0
diff --git a/studio/backend/tests/test_diffusion_more_families.py b/studio/backend/tests/test_diffusion_more_families.py
index 5c4b8841dbd..f8d556fa321 100644
--- a/studio/backend/tests/test_diffusion_more_families.py
+++ b/studio/backend/tests/test_diffusion_more_families.py
@@ -617,3 +617,100 @@ def test_flux2_gguf_base_mismatch_check_fails_open(tmp_path):
assert_flux2_gguf_matches_base(
detect_family("unsloth/FLUX.1-dev-GGUF"), "black-forest-labs/FLUX.2-klein-4B", empty
)
+
+
+def test_qwen_image_21_is_reachable_end_to_end_not_just_detectable():
+ """A family whose base repo is not trusted is not a family at all.
+
+ Detection resolving is the easy half and was never the problem: the load is refused several
+ layers later, by a check that reads a different list, so the entry shipped looking complete and
+ every non-GGUF pick of it died with "restricted to unsloth/* repos". This asserts the whole
+ chain the picker actually walks, which is why it is one test rather than four.
+ """
+ from core.inference.diffusion_families import (
+ _PIPELINE_MIN_DIFFUSERS,
+ detect_family,
+ detect_family_by_pipeline_class,
+ )
+
+ fam = detect_family("Qwen/Qwen-Image-2.1")
+ assert fam is not None and fam.name == "qwen-image-2.1"
+ # Not swallowed by the generic family, and not swallowing it either.
+ assert detect_family("Qwen/Qwen-Image").name == "qwen-image"
+ assert detect_family("Qwen/Qwen-Image-2512").name == "qwen-image"
+ for alias in ("qwen_image_21", "qwenimage21", "qwen-image-21"):
+ assert detect_family("", override = alias) is fam, alias
+ # The class really is what the published model_index.json names.
+ assert detect_family_by_pipeline_class("QwenImage21Pipeline") is fam
+ assert fam.pipeline_class in _PIPELINE_MIN_DIFFUSERS
+
+ # The gate that made the entry inert. _is_trusted_diffusion_repo is asked of the base repo by
+ # validate_load_request BEFORE anything is built, so a family base missing from that list is
+ # unloadable however correct the rest of the entry is.
+ assert _is_trusted_diffusion_repo(fam.base_repo), (
+ f"{fam.base_repo} is the family's own base and is not in _TRUSTED_NON_GGUF_REPOS, so "
+ "every non-GGUF pick of this family is refused before the pipeline is built"
+ )
+
+
+def test_every_image_family_base_repo_is_loadable():
+ """The general form of the above, so the next family cannot ship inert the same way."""
+ from core.inference.diffusion_families import _FAMILIES
+
+ unreachable = [
+ f.name for f in _FAMILIES if f.base_repo and not _is_trusted_diffusion_repo(f.base_repo)
+ ]
+ assert (
+ not unreachable
+ ), f"these families declare a base repo that validate_load_request refuses: {unreachable}"
+
+
+def test_a_minimum_that_has_not_shipped_does_not_prescribe_an_impossible_upgrade():
+ """``pip install -U 'diffusers>=0.41.0'`` has no candidate while 0.41.0 is unreleased, so the
+ refusal has to name the pinned main build Studio actually installs for this class."""
+ from core.inference.diffusion_families import (
+ _PIPELINE_MIN_DIFFUSERS,
+ _UNRELEASED_MIN_DIFFUSERS,
+ _too_old_message,
+ )
+
+ message = _too_old_message("QwenImage21Pipeline", "qwen-image-2.1", "0.40.0")
+ assert "pip install -U 'diffusers>=0.41.0'" not in message
+ assert "diffusers-main.txt" in message
+ assert "has not been released yet" in message
+
+ # A released minimum keeps the ordinary remedy.
+ released = _too_old_message("Krea2Pipeline", "krea-2", "0.38.0")
+ assert "pip install -U 'diffusers>=0.39.0'" in released
+
+ # Every unreleased entry must still be a minimum some class actually declares, so a stale one
+ # cannot sit here unnoticed after its release ships.
+ declared = set(_PIPELINE_MIN_DIFFUSERS.values())
+ assert _UNRELEASED_MIN_DIFFUSERS <= declared, sorted(_UNRELEASED_MIN_DIFFUSERS - declared)
+
+
+def test_qwen_image_21_takes_reference_images_but_is_not_an_edit_only_family():
+ """2.1 is unified, so it is the FLUX.2 shape and not the Qwen-Image-Edit one.
+
+ ``QwenImage21Pipeline.__call__`` takes ``image`` as optional condition images beside the prompt,
+ with no ``strength`` and the size from width/height, which is what the reference workflow passes.
+ ``edit`` would mean the pipeline IS the edit pipeline with no plain text-to-image, which is
+ Qwen-Image-Edit, a different model with a different pipeline class. Getting this wrong in either
+ direction is silent: False refuses reference images outright, True would demand an input image
+ for every generation.
+ """
+ from core.inference.diffusion_families import detect_family
+
+ fam = detect_family("Qwen/Qwen-Image-2.1")
+ assert fam is not None and fam.name == "qwen-image-2.1"
+ assert fam.reference is True
+ assert fam.edit is False
+ assert fam.pipeline_class == "QwenImage21Pipeline"
+ # It also has no separate img2img or inpaint pipeline upstream: the one class covers both jobs.
+ assert fam.img2img_pipeline_class is None
+ assert fam.inpaint_pipeline_class is None
+
+ # The edit family is a different model entirely, and must not have been merged into this one.
+ edit = detect_family("Qwen/Qwen-Image-Edit-2511")
+ assert edit is not None and edit.name == "qwen-image-edit" and edit.edit is True
+ assert edit.pipeline_class != fam.pipeline_class
diff --git a/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.check.ts b/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.check.ts
index 0ab648b0ada..e0c581b97e1 100644
--- a/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.check.ts
+++ b/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.check.ts
@@ -109,6 +109,19 @@ assert.equal(
);
// A sibling artifact of an aliased owner groups via the alias' stripped key.
assert.equal(groupForRepoId("Qwen/Qwen-Image-2512-FP8", IMAGE_CATALOG), qwen2512);
+// A dotted version is a DIFFERENT model, not a variant of the undotted one: every 2.1 repo has to
+// land on the 2.1 group, and none of them may fall back to plain Qwen-Image, whose key is a prefix
+// of theirs.
+const qwen21 = groupForRepoId("Qwen/Qwen-Image-2.1", IMAGE_CATALOG);
+assert.ok(qwen21);
+assert.equal(qwen21.canonicalId, "unsloth/Qwen-Image-2.1");
+assert.equal(groupForRepoId("unsloth/Qwen-Image-2.1-FP8", IMAGE_CATALOG), qwen21);
+assert.equal(groupForRepoId("unsloth/Qwen-Image-2.1-INT8", IMAGE_CATALOG), qwen21);
+assert.notEqual(groupForRepoId("Qwen/Qwen-Image", IMAGE_CATALOG), qwen21);
+assert.equal(
+ groupForRepoId("Qwen/Qwen-Image", IMAGE_CATALOG)?.canonicalId,
+ "unsloth/Qwen-Image",
+);
// Unknown repos pass through ungrouped.
assert.equal(groupForRepoId("someone/some-model-GGUF", IMAGE_CATALOG), null);
assert.equal(groupForRepoId("unsloth/Llama-3.3-70B-GGUF", VIDEO_CATALOG), null);
diff --git a/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts b/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts
index f21a4a0c1d4..1336ffa06f6 100644
--- a/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts
+++ b/studio/frontend/src/features/model-picker/components/model-selector/model-catalog.ts
@@ -179,6 +179,24 @@ export const IMAGE_CATALOG: CatalogGroup[] = [
scope: "image",
artifacts: [gguf("unsloth/Z-Image-GGUF")],
},
+ {
+ canonicalId: "unsloth/Qwen-Image-2.1",
+ displayName: "Qwen-Image 2.1",
+ // Text-to-image that also accepts reference images on the same call (the family's `reference`
+ // flag), rather than a separate edit pipeline the way Qwen-Image-Edit is.
+ description: "Text-to-image",
+ scope: "image",
+ // Same reason as the 2512 row below: the int8 half of the prequant repo is reached through
+ // prequant_variant_repos and has no artifact row, so alias it to keep a pasted id finding it.
+ aliases: ["unsloth/Qwen-Image-2.1-FP8"],
+ artifacts: [
+ bf16Pipeline("Qwen/Qwen-Image-2.1", 33, {
+ totalParams: 7115124736,
+ prequantRepo: "unsloth/Qwen-Image-2.1-FP8",
+ prequantSizeGb: { fp8: 7.12, int8: 7.26 },
+ }),
+ ],
+ },
{
canonicalId: "unsloth/Qwen-Image-2512",
displayName: "Qwen-Image 2512",
diff --git a/studio/install_python_stack.py b/studio/install_python_stack.py
index 76830041041..3cef5061d78 100644
--- a/studio/install_python_stack.py
+++ b/studio/install_python_stack.py
@@ -9322,11 +9322,15 @@ def _parse_pinned_pip_config(
def pip_install_try(
label: str,
*args: str,
+ req: Path | None = None,
constrain: bool = True,
force_pip: bool = False,
) -> bool:
"""Like pip_install but returns False on failure instead of exiting.
For optional installs that have a follow-up fallback.
+
+ ``req`` goes through ``_effective_requirements`` exactly as in pip_install, so a file
+ installed through either entry point is the same file the install-manifest gate audits.
"""
# Same reason as pip_install: this installs torch too (the Windows AMD ROCm trio),
# so the memoized classification must not survive it.
@@ -9339,19 +9343,33 @@ def pip_install_try(
constraint_args_pip = ["-c", str(CONSTRAINTS)]
constraint_args_uv = ["-c", _uv_safe_path(CONSTRAINTS)]
+ actual_req = req
+ temp_reqs: list[Path] = []
+ if req is not None:
+ actual_req, temp_reqs = _effective_requirements(req)
+ req_args_pip: list[str] = []
+ req_args_uv: list[str] = []
+ if actual_req is not None:
+ req_args_pip = ["-r", str(actual_req)]
+ req_args_uv = ["-r", _uv_safe_path(actual_req)]
+
if USE_UV and not force_pip:
- cmd, env = _pinned_cmd_and_env(_build_uv_cmd(args) + constraint_args_uv)
+ cmd, env = _pinned_cmd_and_env(_build_uv_cmd(args) + constraint_args_uv + req_args_uv)
else:
- cmd, env = _pinned_cmd_and_env(_build_pip_cmd(args) + constraint_args_pip)
+ cmd, env = _pinned_cmd_and_env(_build_pip_cmd(args) + constraint_args_pip + req_args_pip)
if VERBOSE:
_step(_LABEL, f"{label}...", _dim)
- result = subprocess.run(
- cmd,
- stdout = subprocess.PIPE,
- stderr = subprocess.STDOUT,
- env = env,
- )
+ try:
+ result = subprocess.run(
+ cmd,
+ stdout = subprocess.PIPE,
+ stderr = subprocess.STDOUT,
+ env = env,
+ )
+ finally:
+ for temp_req in temp_reqs:
+ temp_req.unlink(missing_ok = True)
if result.returncode == 0:
# As pip_install below: `nobuild` only catches a build that reaches the log.
if VERBOSE and result.stdout:
@@ -10306,6 +10324,7 @@ def _skip_step(
no_deps: bool,
constrain: bool = True,
extra_check = None,
+ superseded: bool = False,
) -> bool:
"""Announce one requirements step and say whether it is already satisfied.
@@ -10314,12 +10333,22 @@ def _skip_step(
*extra_check* is an on-disk predicate for a file importlib.metadata cannot fully answer:
today only triton-kernels.txt, whose git ref no version reflects.
+
+ *superseded* says a LATER step has already put a different build of this distribution in
+ place, one this file's version pin cannot describe. The requirement really is unsatisfied and
+ must still not run: running it would undo the step that supersedes it, which would then redo
+ itself, so every pass reinstalls twice and no update is ever a no-op. Deliberately separate
+ from *extra_check*, which can only make an answer stricter.
"""
key = _pass_input_key(req) or str(req)
if not no_deps and _pass_input_key(req) is not None:
# Registered whether or not skipped, so the first pass records what its closure cannot
# satisfy.
_AUDITED_STEPS[key] = req
+ if superseded:
+ _progress(f"{progress_label} (superseded, skipped)")
+ _record_step(key, "skipped")
+ return True
satisfied = _requirements_satisfied(req, no_deps = no_deps, constrain = constrain)
if satisfied and extra_check is not None:
satisfied = bool(extra_check())
@@ -10462,6 +10491,131 @@ def _triton_kernels_step() -> None:
)
+DIFFUSERS_MAIN_ENV = "UNSLOTH_DIFFUSERS_MAIN"
+
+# Diffusers main declares requires-python >= 3.10 while the release pin file still names 0.36.0
+# for anything older, so 3.9 is a supported install this step can never satisfy.
+DIFFUSERS_MAIN_MIN_PYTHON = (3, 10)
+
+
+def _diffusers_main_requested() -> bool:
+ """Whether this install wants the pinned Diffusers main build. Default: yes.
+
+ Opt OUT with ``UNSLOTH_DIFFUSERS_MAIN=0`` (also false/no/off). Anything else, including the
+ variable being unset, means yes, so the models that need an unreleased Diffusers work for
+ everyone without a flag. The opt-out exists for an install that must stay on the exact release
+ everything else is built against, or that cannot reach github.com but does have git.
+ """
+ value = (os.environ.get(DIFFUSERS_MAIN_ENV) or "").strip().lower()
+ return value not in ("0", "false", "no", "off")
+
+
+def _diffusers_main_resident(req: "Path | None" = None) -> bool:
+ """Whether the pinned main build is BOTH what the file names and actually on disk.
+
+ Provenance alone is not a build, the same reason ``_triton_kernels_step`` pairs its ref check
+ with this one: ``direct_url.json`` survives inside dist-info while the package tree under it is
+ deleted or truncated, and a provenance-only answer would skip the reinstall AND, since the
+ release pin reads the same predicate to decide it has been superseded, skip the repair too.
+ Diffusers is mandatory, so that combination leaves Studio broken on every later pass rather
+ than for one. Either half failing means "install it", which is the recoverable direction.
+ """
+ if req is None:
+ req = REQ_ROOT / "diffusers-main.txt"
+ return _direct_reference_is_installed(req, "diffusers") and _payload_recorded_intact(
+ "diffusers"
+ )
+
+
+def _diffusers_main_supersedes_release() -> bool:
+ """Whether 11c's build already stands in for the release pin, so 11b must not reinstall it.
+
+ Only when the main build is BOTH wanted and resident, AND this pass is allowed to skip work at
+ all: under UNSLOTH_STUDIO_FULL_DEPS both steps run, the release first and the commit back on
+ top, which is the same order a first install takes and the only order that ends with the tree
+ the family gate expects.
+ """
+ if _full_deps_requested():
+ return False
+ return _diffusers_main_requested() and _diffusers_main_resident()
+
+
+def _diffusers_main_step() -> None:
+ """Install the pinned Diffusers commit, or leave the release pin alone.
+
+ Three things this has to get right, none of which the ordinary ``_skip_step`` path covers:
+
+ * A VERSION says nothing here. Every build of main reports 0.41.0.dev0, so the usual "is the
+ requirement satisfied" check passes against a build from any other commit, or against the
+ release the previous step just installed. ``_direct_reference_is_installed`` reads the ref out
+ of direct_url.json, which is the only place it survives, so bumping the commit in the file
+ actually reinstalls instead of silently keeping the old tree.
+ * Diffusers is MANDATORY, unlike triton_kernels, so a host that cannot do a source build must
+ not be left with a broken install. It is not: the release pin ran first and is already in
+ place, so skipping here leaves a working Studio that simply cannot load the newest model.
+ That is the whole reason this is a second step on top of the release pin rather than an
+ edit to it, now that it runs by default and therefore meets every host there is.
+ * Opting out must put the release back. Setting the variable to 0 and re-running reinstalls the
+ pin on the next pass, because the pin step's own inputs are unchanged but the resident
+ diffusers is no longer what the release pin names.
+
+ It spends exactly ONE progress slot on every path, including opting out, because the total is
+ fixed before any of this is known. An early return without a _progress leaves the bar short of
+ its own total for precisely the users who opted out.
+ """
+ if not _diffusers_main_requested():
+ _progress("diffusers main (opted out, skipped)")
+ return
+ if sys.version_info < DIFFUSERS_MAIN_MIN_PYTHON:
+ # Diffusers main needs 3.10, and the release pin file still carries a 0.36.0 line for
+ # older interpreters, so 3.9 is a supported path this can never satisfy. Unmarked, pip would
+ # clone the repository and only then reject its requires-python, and since the build can
+ # never become resident that clone repeats on every install and update forever.
+ _progress("diffusers main (skipped, needs python 3.10)")
+ return
+ req = REQ_ROOT / "diffusers-main.txt"
+ if not req.is_file():
+ _progress("diffusers main (skipped, no pin file)")
+ return
+ if not _has_working_git():
+ _progress("diffusers main (skipped, no git)")
+ _note(
+ "No working git, so this install keeps the pinned Diffusers release instead of the "
+ "pinned main build. Everything else works; models that need an unreleased Diffusers "
+ "will refuse with a message naming the version they want.",
+ )
+ return
+ # The escape hatch reaches this skip too. UNSLOTH_STUDIO_FULL_DEPS is the documented way to
+ # repair an install whose evidence looks fine and whose payload is not, and _diffusers_main_resident
+ # is exactly such evidence: _payload_recorded_intact compares recorded sizes, so a same-size
+ # corruption reads as intact. A skip nobody can turn off is a bug nobody can work around.
+ if not _full_deps_requested() and _diffusers_main_resident(req):
+ _progress("diffusers main (satisfied, skipped)")
+ _record_step("diffusers-main.txt", "skipped")
+ return
+ _progress("diffusers main")
+ _record_step("diffusers-main.txt", "ran")
+ # pip_install_try, NOT pip_install, and this is the whole reason the step is safe to run by
+ # default. pip_install exits the installer on failure, which would make a reachable github.com
+ # a hard requirement of every install: a PyPI mirror with no route out, a proxy that blocks git
+ # over https, a transient upstream outage would each turn a working install into no install at
+ # all. Diffusers is mandatory, so the failure has to be survivable, and it is exactly survivable
+ # because the release pin ran first and is still resident. Degrading costs one model.
+ if not pip_install_try(
+ "Installing the pinned Diffusers main build",
+ "--no-cache-dir",
+ req = req,
+ constrain = False,
+ ):
+ _record_step("diffusers-main.txt", "skipped")
+ _note(
+ "Could not install the pinned Diffusers main build, so this install keeps the pinned "
+ "Diffusers release. Everything else works; models that need an unreleased Diffusers "
+ f"will refuse with a message naming the version they want. Set {DIFFUSERS_MAIN_ENV}=0 "
+ "to stop trying.",
+ )
+
+
def _recorded_direct_url(dist_name: str) -> "dict | None":
"""The direct_url.json pip and uv wrote for *dist_name*, or None when there is none
that parses. This is the only place a git install's ref and commit survive."""
@@ -10710,9 +10864,10 @@ def install_python_stack() -> int:
# reinstall path too, not just the two calls below
# Clean-machine CI overlays only unsloth, not the full local source pair.
ci_source_overlay = os.environ.get("UNSLOTH_CI_SOURCE_OVERLAY", "")
- # Four lettered steps beside the numbered ones: anyio repair (8b), accelerate repair
- # (8c, Windows only), diffusers pin (11b), torchcodec (13b).
- base_total = 13 if IS_WINDOWS else 14
+ # Five lettered steps beside the numbered ones: anyio repair (8b), accelerate repair
+ # (8c, Windows only), diffusers pin (11b), diffusers main (11c), torchcodec (13b).
+ # 11c is counted unconditionally because it spends its slot unconditionally, opt-out included.
+ base_total = 14 if IS_WINDOWS else 15
if IS_WINDOWS:
base_total += 1 # 8c, gated exactly as the step is
if IS_MACOS:
@@ -11218,13 +11373,32 @@ def install_python_stack() -> int:
# release, and outside every skip_base / NO_TORCH branch so it reaches every path.
# constrain stays on: constraints.txt says nothing about diffusers today, and a
# future entry there should win rather than be silently bypassed here.
- if not _skip_step(REQ_ROOT / "diffusers-pin.txt", "diffusers pin", no_deps = False):
+ # And it stands down once 11c's build is resident. Nothing here can see that on its own: a
+ # main build reports 0.41.0.dev0, which does not satisfy `diffusers==0.40.0`, so this step
+ # would reinstall the release on every later pass and 11c would put the same commit back on
+ # top of it. Two Diffusers installs per update, no update that is a no-op, and offline the
+ # downgrade lands while the restore cannot. Only a build that is BOTH wanted and already
+ # resident supersedes it, so opting out still reinstates the release, and a first install
+ # still lays it down first, which is what a failed source build degrades to.
+ if not _skip_step(
+ REQ_ROOT / "diffusers-pin.txt",
+ "diffusers pin",
+ no_deps = False,
+ superseded = _diffusers_main_supersedes_release(),
+ ):
pip_install(
"Installing the pinned Diffusers release",
"--no-cache-dir",
req = REQ_ROOT / "diffusers-pin.txt",
)
+ # 11c. A pinned commit of Diffusers main, for models whose support has merged upstream but has
+ # not reached a release. ON by default; UNSLOTH_DIFFUSERS_MAIN=0 opts out. Runs immediately
+ # after the release pin so it overwrites it, and only ever on top of it: the release is
+ # already resident, so no git and a failed source build both degrade to a working install
+ # rather than no install.
+ _diffusers_main_step()
+
# 12. Patch metadata for single-env compatibility
_finalize_ran = _dd_deps_ran or _dd_ran or _patch_metadata_is_pending()
_progress("finalizing" if _finalize_ran else "finalizing (satisfied, skipped)")
diff --git a/tests/python/test_windows_arm64_wheelhouse_tags.py b/tests/python/test_windows_arm64_wheelhouse_tags.py
index 9df44ecb44d..69680f21ade 100644
--- a/tests/python/test_windows_arm64_wheelhouse_tags.py
+++ b/tests/python/test_windows_arm64_wheelhouse_tags.py
@@ -1470,7 +1470,15 @@ class TestTheSkipGateAuditsTheArm64FilteredFile:
assert "_windows_arm64_skip_packages(actual)" not in helper
def test_pip_install_and_the_audits_share_it(self, ips):
- """Three call sites: the install, the closure record, and the on-disk skip check."""
+ """Four call sites: both installs, the closure record, and the on-disk skip check.
+
+ The count is the invariant's teeth, not the invariant itself: every path that installs a
+ requirements file, or reasons about one, has to filter it the same way, or a caller decides
+ a pin is satisfied against a file different from the one that was installed. ``pip_install``
+ and ``pip_install_try`` are now both such paths, so a fourth shared call site is the
+ invariant holding rather than loosening. A caller that grew its own filtering would still
+ show up here, as a count that moved without a matching call site.
+ """
assert (
- STACK_SRC.count("_effective_requirements(req)") == 3
+ STACK_SRC.count("_effective_requirements(req)") == 4
), "a caller that filters its own way can disagree with the file that installs"
diff --git a/tests/studio/install/test_diffusers_pin.py b/tests/studio/install/test_diffusers_pin.py
index 6a46bf872bc..434f26e84e6 100644
--- a/tests/studio/install/test_diffusers_pin.py
+++ b/tests/studio/install/test_diffusers_pin.py
@@ -27,6 +27,11 @@ import pytest
REPO_ROOT = pathlib.Path(__file__).resolve().parents[3]
REQ_ROOT = REPO_ROOT / "studio" / "backend" / "requirements"
PIN_FILE = REQ_ROOT / "diffusers-pin.txt"
+# The commit pin, installed by default ON TOP of the release pin. Exempt from the
+# one-source-of-truth scan below because it is the one deliberate second namer of diffusers: it is
+# installed by the step immediately after the release pin and by nothing else, which the tests here
+# pin down rather than assume.
+MAIN_FILE = REQ_ROOT / "diffusers-main.txt"
# The shape install_python_stack._filter_requirements writes: a dot, the source stem,
# "-filtered-", then tempfile's random suffix. NamedTemporaryFile's suffixes are
@@ -87,7 +92,7 @@ def test_only_the_pin_file_names_diffusers():
whichever step runs last wins, and the step order is not obvious from any one file."""
offenders = {}
for path in sorted(REQ_ROOT.rglob("*.txt")):
- if path == PIN_FILE:
+ if path in (PIN_FILE, MAIN_FILE):
continue
# install_python_stack._filter_requirements writes `.{stem}-filtered-XXXX.txt` BESIDE the source on purpose, so
# relative -r/-c includes still resolve, and it does not delete it.
@@ -100,11 +105,161 @@ def test_only_the_pin_file_names_diffusers():
if named:
offenders[str(path.relative_to(REPO_ROOT))] = named
assert not offenders, (
- f"diffusers is requirement-listed outside diffusers-pin.txt: {offenders}. "
+ f"diffusers is requirement-listed outside diffusers-pin.txt and diffusers-main.txt: "
+ f"{offenders}. "
f"Move it into the pin file so the dedicated late step remains authoritative."
)
+def test_the_main_build_pins_a_commit_and_runs_after_the_release():
+ """The main-build file exists, names a COMMIT, and runs after the release pin.
+
+ The commit is the load-bearing part and is asserted rather than trusted: a branch ref would
+ leave nothing pinning behaviour, because any main build reports 0.41.0.dev0 and
+ ``_version_tuple`` truncates it to (0, 41, 0), so no version check can tell two apart. Now that
+ this installs by default that is a stronger requirement, not a weaker one, since the whole user
+ base would otherwise be on whatever main happened to be that morning.
+ """
+ assert MAIN_FILE.is_file(), f"{MAIN_FILE} is missing"
+ lines = _requirements(MAIN_FILE)
+ assert len(lines) == 1, lines
+ spec = lines[0]
+ assert spec.startswith("diffusers @ git+"), spec
+ revision = spec.rpartition("@")[2].strip()
+ assert re.fullmatch(r"[0-9a-f]{40}", revision), (
+ f"{MAIN_FILE.name} must pin a full 40-character commit, not {revision!r}: a branch ref "
+ "moves under an unchanged requirements file and nothing in Unsloth can tell two builds of "
+ "main apart"
+ )
+
+ source = _code_only(STACK.read_text(encoding = "utf-8"))
+ # Installed only through its own step, which reads the opt-out.
+ assert "diffusers-main.txt" in source
+ assert "_diffusers_main_requested" in source
+ assert "UNSLOTH_DIFFUSERS_MAIN" in source
+ # And the CALL runs after the release pin install, or the release would overwrite it. Compared
+ # on the call site, not on the filename: the helper is DEFINED earlier in the file than either
+ # install, so a filename compare answers a different question and passes by accident.
+ call = "\n _diffusers_main_step()\n"
+ assert call in source, "the main-build step is never called"
+ assert source.index(call) > source.index('req = REQ_ROOT / "diffusers-pin.txt"')
+
+
+def _probe_module(name: str):
+ import importlib.util
+
+ spec = importlib.util.spec_from_file_location(name, STACK)
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ return module
+
+
+def test_the_main_build_is_on_by_default_and_opts_out_on_zero(monkeypatch):
+ """Default ON is the whole point, so the unset case is asserted, not assumed.
+
+ The opt-out is deliberately narrow: only an explicit falsy value turns it off, because a typo
+ in the variable name silently disabling a model is the worse failure of the two.
+ """
+ module = _probe_module("install_python_stack_probe")
+
+ monkeypatch.delenv("UNSLOTH_DIFFUSERS_MAIN", raising = False)
+ assert module._diffusers_main_requested() is True
+ for value in ("", "1", "true", "YES", "on", "anything"):
+ monkeypatch.setenv("UNSLOTH_DIFFUSERS_MAIN", value)
+ assert module._diffusers_main_requested() is True, value
+ for value in ("0", "false", "NO", "off", " off "):
+ monkeypatch.setenv("UNSLOTH_DIFFUSERS_MAIN", value)
+ assert module._diffusers_main_requested() is False, value
+
+ # And opting out really stops the step, rather than only stopping the message.
+ monkeypatch.setenv("UNSLOTH_DIFFUSERS_MAIN", "0")
+ monkeypatch.setattr(
+ module, "pip_install_try", lambda *a, **k: pytest.fail("the step ran after opting out")
+ )
+ # _progress divides by a total the standalone module never set.
+ progressed = []
+ monkeypatch.setattr(module, "_progress", lambda label, *a, **k: progressed.append(label))
+ monkeypatch.setattr(module, "_note", lambda *a, **k: None)
+ module._diffusers_main_step()
+ # It still spends its slot. The total is fixed before the opt-out is known, so returning early
+ # without a _progress leaves the bar stuck short of its own total for exactly these users.
+ assert len(progressed) == 1, progressed
+
+
+def test_the_main_build_keeps_the_release_when_there_is_no_git(monkeypatch):
+ """Diffusers is mandatory, unlike triton_kernels, so a host with no working git must be left
+ with the release the previous step installed rather than nothing at all."""
+ module = _probe_module("install_python_stack_probe2")
+
+ monkeypatch.delenv("UNSLOTH_DIFFUSERS_MAIN", raising = False)
+ monkeypatch.setattr(module, "_has_working_git", lambda: False)
+ monkeypatch.setattr(
+ module, "pip_install_try", lambda *a, **k: pytest.fail("a git requirement without git")
+ )
+ monkeypatch.setattr(module, "_progress", lambda *a, **k: None)
+ notes = []
+ monkeypatch.setattr(module, "_note", lambda msg, *a, **k: notes.append(msg))
+ module._diffusers_main_step()
+ # And it SAYS so, rather than leaving the install looking like it got the main build.
+ assert notes and "no working git" in notes[0].lower()
+
+
+def test_a_failed_main_build_degrades_instead_of_failing_the_install(monkeypatch):
+ """The one that makes default-on safe.
+
+ ``pip_install`` exits the installer. Using it here would make a reachable github.com a hard
+ requirement of installing Unsloth: a blocked proxy, an offline mirror or an upstream outage
+ would turn a working install into no install. The release pin is already resident, so the
+ failure is survivable and must be survived.
+ """
+ module = _probe_module("install_python_stack_probe3")
+
+ monkeypatch.delenv("UNSLOTH_DIFFUSERS_MAIN", raising = False)
+ monkeypatch.setattr(module, "_has_working_git", lambda: True)
+ monkeypatch.setattr(module, "_direct_reference_is_installed", lambda *a, **k: False)
+ monkeypatch.setattr(module, "_progress", lambda *a, **k: None)
+ monkeypatch.setattr(
+ module, "pip_install", lambda *a, **k: pytest.fail("pip_install exits the installer")
+ )
+ attempted = []
+ monkeypatch.setattr(
+ module, "pip_install_try", lambda *a, **k: (attempted.append(k.get("req")), False)[1]
+ )
+ notes = []
+ monkeypatch.setattr(module, "_note", lambda msg, *a, **k: notes.append(msg))
+ steps = {}
+ monkeypatch.setattr(module, "_record_step", lambda name, state: steps.__setitem__(name, state))
+
+ module._diffusers_main_step()
+
+ assert attempted and attempted[0].name == "diffusers-main.txt"
+ assert (
+ steps["diffusers-main.txt"] == "skipped"
+ ), "a failed build recorded as 'ran' would report an install that never happened"
+ assert notes and "keeps the pinned" in notes[0]
+
+
+def test_the_main_build_is_satisfied_without_touching_the_network(monkeypatch):
+ """A full SHA is answerable from direct_url.json, and on by default this runs on every pass."""
+ module = _probe_module("install_python_stack_probe4")
+
+ monkeypatch.delenv("UNSLOTH_DIFFUSERS_MAIN", raising = False)
+ monkeypatch.setattr(module, "_has_working_git", lambda: True)
+ monkeypatch.setattr(module, "_direct_reference_is_installed", lambda *a, **k: True)
+ # Provenance AND payload: residency needs both, and a test environment with no installed
+ # Diffusers payload would otherwise fall through to the failing stub below and blame the step.
+ monkeypatch.setattr(module, "_payload_recorded_intact", lambda *a, **k: True)
+ monkeypatch.setattr(module, "_progress", lambda *a, **k: None)
+ monkeypatch.setattr(module, "_note", lambda *a, **k: None)
+ monkeypatch.setattr(
+ module, "pip_install_try", lambda *a, **k: pytest.fail("reinstalled an installed pin")
+ )
+ steps = {}
+ monkeypatch.setattr(module, "_record_step", lambda name, state: steps.__setitem__(name, state))
+ module._diffusers_main_step()
+ assert steps["diffusers-main.txt"] == "skipped"
+
+
def test_the_pin_step_is_not_gated_by_skip_base_or_no_torch():
"""The pin must sit at function top level so it reaches every install path."""
tree = ast.parse(STACK.read_text(encoding = "utf-8"))
@@ -266,3 +421,192 @@ def test_the_win_arm64_floor_is_the_first_release_that_has_a_wheel(relpath, dist
):
continue
assert line in wanted, f"{relpath}: a second ARM64 floor for {dist}: {line}"
+
+
+def test_the_release_pin_stands_down_once_the_main_build_is_resident(monkeypatch):
+ """The one that makes a second update a no-op.
+
+ The release pin is a version pin and the main build reports ``0.41.0.dev0``, so the pin never
+ reads as satisfied once the commit is in place. Left alone it reinstalls the release on every
+ pass and the step after it reinstalls the same commit on top, which is two Diffusers installs
+ per update and an offline update that downgrades a working build and then cannot restore it.
+ """
+ module = _probe_module("install_python_stack_probe5")
+
+ calls = []
+ monkeypatch.setattr(module, "_progress", lambda label, *a, **k: calls.append(label))
+ monkeypatch.setattr(module, "_record_step", lambda *a, **k: None)
+ monkeypatch.setattr(module, "_requirements_satisfied", lambda *a, **k: False)
+
+ # Resident and wanted: the step must not run, and must still spend its slot.
+ assert (
+ module._skip_step(
+ module.REQ_ROOT / "diffusers-pin.txt",
+ "diffusers pin",
+ no_deps = False,
+ superseded = True,
+ )
+ is True
+ )
+ assert len(calls) == 1 and "skipped" in calls[0], calls
+
+ # Not superseded: unchanged, so a first install and an opt-out both still get the release.
+ calls.clear()
+ assert (
+ module._skip_step(
+ module.REQ_ROOT / "diffusers-pin.txt",
+ "diffusers pin",
+ no_deps = False,
+ superseded = False,
+ )
+ is False
+ )
+ assert calls == ["diffusers pin"], calls
+
+
+def test_opting_out_or_a_missing_main_build_still_reinstates_the_release(monkeypatch):
+ """The supersession is narrow on purpose: it is the ONLY thing standing between an opt-out and
+ a Studio left on a main build it asked not to have."""
+ module = _probe_module("install_python_stack_probe6")
+ main_req = module.REQ_ROOT / "diffusers-main.txt"
+
+ monkeypatch.setattr(module, "_direct_reference_is_installed", lambda *a, **k: True)
+ monkeypatch.delenv("UNSLOTH_DIFFUSERS_MAIN", raising = False)
+ assert module._diffusers_main_requested() and module._direct_reference_is_installed(
+ main_req, "diffusers"
+ )
+
+ monkeypatch.setenv("UNSLOTH_DIFFUSERS_MAIN", "0")
+ assert not (
+ module._diffusers_main_requested()
+ and module._direct_reference_is_installed(main_req, "diffusers")
+ ), "opting out must let the release pin run again"
+
+ monkeypatch.delenv("UNSLOTH_DIFFUSERS_MAIN", raising = False)
+ monkeypatch.setattr(module, "_direct_reference_is_installed", lambda *a, **k: False)
+ assert not (
+ module._diffusers_main_requested()
+ and module._direct_reference_is_installed(main_req, "diffusers")
+ ), "a first install must lay the release down before the commit goes on top of it"
+
+
+def test_a_damaged_main_build_is_repaired_rather_than_believed(monkeypatch):
+ """Provenance alone is not a build, and here that is worse than it is for triton kernels.
+
+ ``direct_url.json`` survives inside dist-info while the package tree under it is deleted or
+ truncated. The release pin reads the same predicate to decide it has been superseded, so a
+ provenance-only answer would skip the reinstall AND the repair, on a MANDATORY dependency, on
+ every later pass rather than one. Either half failing has to mean "install it".
+ """
+ module = _probe_module("install_python_stack_probe7")
+ monkeypatch.delenv("UNSLOTH_DIFFUSERS_MAIN", raising = False)
+
+ monkeypatch.setattr(module, "_direct_reference_is_installed", lambda *a, **k: True)
+ monkeypatch.setattr(module, "_payload_recorded_intact", lambda *a, **k: True)
+ assert module._diffusers_main_resident() is True
+
+ # The ref still points at the right commit, the files under it are gone.
+ monkeypatch.setattr(module, "_payload_recorded_intact", lambda *a, **k: False)
+ assert (
+ module._diffusers_main_resident() is False
+ ), "a damaged payload must not read as installed"
+ # And with it False, the release pin is no longer superseded, so the repair really can run.
+ assert not (module._diffusers_main_requested() and module._diffusers_main_resident())
+
+ # The step itself reinstalls rather than reporting satisfied.
+ attempted = []
+ monkeypatch.setattr(module, "_has_working_git", lambda: True)
+ monkeypatch.setattr(module, "_progress", lambda *a, **k: None)
+ monkeypatch.setattr(module, "_note", lambda *a, **k: None)
+ monkeypatch.setattr(module, "_record_step", lambda *a, **k: None)
+ monkeypatch.setattr(
+ module, "pip_install_try", lambda *a, req = None, **k: (attempted.append(req), True)[1]
+ )
+ module._diffusers_main_step()
+ assert attempted and attempted[0].name == "diffusers-main.txt"
+
+
+def test_python_39_does_not_clone_a_build_it_can_never_install(monkeypatch):
+ """diffusers-pin.txt still names 0.36.0 below 3.10, so 3.9 is a supported install, and main
+ declares requires-python >= 3.10. Unmarked, pip clones the repository and only then rejects
+ it, and since the build can never become resident that clone repeats on every update."""
+ module = _probe_module("install_python_stack_probe8")
+ monkeypatch.delenv("UNSLOTH_DIFFUSERS_MAIN", raising = False)
+ monkeypatch.setattr(
+ module, "pip_install_try", lambda *a, **k: pytest.fail("cloned main on python 3.9")
+ )
+ monkeypatch.setattr(module, "_has_working_git", lambda: True)
+ monkeypatch.setattr(module, "_note", lambda *a, **k: None)
+
+ class _V(tuple):
+ pass
+
+ monkeypatch.setattr(module.sys, "version_info", _V((3, 9, 21)))
+ progressed: list = []
+ monkeypatch.setattr(module, "_progress", lambda label, *a, **k: progressed.append(label))
+ module._diffusers_main_step()
+ # The slot is still spent: the denominator is fixed before the interpreter is consulted.
+ assert len(progressed) == 1 and "python 3.10" in progressed[0], progressed
+
+ # And the release pin is NOT superseded there, so 3.9 keeps getting its 0.36.0.
+ monkeypatch.setattr(module, "_direct_reference_is_installed", lambda *a, **k: False)
+ assert not (module._diffusers_main_requested() and module._diffusers_main_resident())
+
+ # 3.10 is unaffected.
+ attempted: list = []
+ monkeypatch.setattr(module.sys, "version_info", _V((3, 10, 0)))
+ monkeypatch.setattr(module, "_payload_recorded_intact", lambda *a, **k: False)
+ monkeypatch.setattr(
+ module, "pip_install_try", lambda *a, req = None, **k: (attempted.append(req), True)[1]
+ )
+ monkeypatch.setattr(module, "_record_step", lambda *a, **k: None)
+ module._diffusers_main_step()
+ assert attempted and attempted[0].name == "diffusers-main.txt"
+
+
+def test_the_full_deps_escape_hatch_reaches_both_diffusers_steps(monkeypatch):
+ """UNSLOTH_STUDIO_FULL_DEPS is the documented repair, and this was the one pin-shaped pair it
+ could not reach.
+
+ ``_diffusers_main_resident`` is exactly the kind of evidence the hatch exists to override:
+ ``_payload_recorded_intact`` compares recorded sizes, so a same-size corruption reads as intact
+ and both steps would skip, leaving nothing to repair Diffusers with.
+ """
+ module = _probe_module("install_python_stack_probe_fulldeps")
+
+ calls: list = []
+ installed: list = []
+ monkeypatch.setattr(module, "_progress", lambda label, *a, **k: calls.append(label))
+ monkeypatch.setattr(module, "_record_step", lambda *a, **k: None)
+ monkeypatch.setattr(module, "_note", lambda *a, **k: None)
+ monkeypatch.setattr(module, "_has_working_git", lambda: True)
+ monkeypatch.setattr(module, "_diffusers_main_resident", lambda req = None: True)
+ monkeypatch.setattr(
+ module, "pip_install_try", lambda *a, **k: (installed.append(k.get("req")), True)[1]
+ )
+ monkeypatch.delenv(module.DIFFUSERS_MAIN_ENV, raising = False)
+
+ # Without the hatch: resident means skip, and the release pin stands down.
+ monkeypatch.delenv(module._FULL_DEPS_ENV, raising = False)
+ module._diffusers_main_step()
+ assert installed == [], installed
+ assert len(calls) == 1 and "satisfied, skipped" in calls[0], calls
+ assert module._diffusers_main_supersedes_release() is True
+
+ # With it: the build is reinstalled, and the release pin runs first so the order is the one a
+ # first install takes.
+ calls.clear()
+ monkeypatch.setenv(module._FULL_DEPS_ENV, "1")
+ module._diffusers_main_step()
+ assert len(installed) == 1, installed
+ assert calls == ["diffusers main"], calls
+ assert module._diffusers_main_supersedes_release() is False
+
+ # Opting out of the main build still wins over the hatch: no source build either way.
+ calls.clear()
+ installed.clear()
+ monkeypatch.setenv(module.DIFFUSERS_MAIN_ENV, "0")
+ module._diffusers_main_step()
+ assert installed == [], installed
+ assert len(calls) == 1 and "opted out" in calls[0], calls
+ assert module._diffusers_main_supersedes_release() is False
diff --git a/tests/studio/install/test_mlx_install.py b/tests/studio/install/test_mlx_install.py
index 15447fc4ab8..a9e6e5751bb 100644
--- a/tests/studio/install/test_mlx_install.py
+++ b/tests/studio/install/test_mlx_install.py
@@ -123,8 +123,10 @@ def test_mlx_install_respects_platform_mode_and_pins(
if platform.startswith("macos"):
# An update without torch announces the no-torch runtime deps on their own slot.
# Two mac-arm slots: the MLX step, and the re-resolve after the core phase.
+ # The +1 is the diffusers main slot (11c), spent on every platform and every path.
assert stack._TOTAL == (
(12 if skip_base and not shared_base else 13)
+ + 1
+ 2 * int(enabled)
+ int(no_torch and not skip_base)
)
@@ -270,11 +272,12 @@ def test_unsupported_apple_silicon_skips_mlx_without_failing_the_install(
assert "MLX stack (skipped, no wheel for this macOS or Python)" in steps
# A skipped step still spends its slot.
# Two mac-arm slots even with no wheel: the re-resolve slot is spent unconditionally.
- assert stack._TOTAL == (12 if skip_base and not shared_base else 13) + 2
+ # Plus the diffusers main slot (11c), which is likewise spent whatever it decides.
+ assert stack._TOTAL == (12 if skip_base and not shared_base else 13) + 1 + 2
def test_supported_and_unsupported_hosts_share_one_progress_budget(monkeypatch):
- """Same total either way, so the bar cannot end at 13/14 on an old Mac."""
+ """Same total either way, so the bar cannot end short of its own total on an old Mac."""
_run_to_extras(
monkeypatch,
platform = "macos_arm",
diff --git a/tests/studio/install/test_windows_torch_flavor_invariant.py b/tests/studio/install/test_windows_torch_flavor_invariant.py
index a45e39dd995..1a77d7f1854 100644
--- a/tests/studio/install/test_windows_torch_flavor_invariant.py
+++ b/tests/studio/install/test_windows_torch_flavor_invariant.py
@@ -329,18 +329,19 @@ def _base_total(**flags) -> int:
class TestStepTotals:
def test_windows_totals_include_torchcodec(self):
# Both carry the Windows-only accelerate repair (8c), which ignores NO_TORCH; the
- # no-torch case also gets the runtime-deps slot an update announces separately.
- assert _base_total(IS_WINDOWS = True) == 16
- assert _base_total(IS_WINDOWS = True, NO_TORCH = True) == 15
+ # no-torch case also gets the runtime-deps slot an update announces separately. Both also
+ # carry the diffusers main slot (11c), which is spent on every path including opting out.
+ assert _base_total(IS_WINDOWS = True) == 17
+ assert _base_total(IS_WINDOWS = True, NO_TORCH = True) == 16
@pytest.mark.parametrize(
"flags,total",
[
- ({}, 17), # Linux, torch
- ({"NO_TORCH": True}, 15), # Linux, GGUF-only (incl. the no-torch runtime step)
+ ({}, 18), # Linux, torch
+ ({"NO_TORCH": True}, 16), # Linux, GGUF-only (incl. the no-torch runtime step)
# Two MLX slots: the install step and the post-core-phase re-resolve.
- ({"IS_MACOS": True, "IS_MAC_ARM": True}, 15), # Apple Silicon
- ({"IS_MACOS": True}, 13), # Intel Mac
+ ({"IS_MACOS": True, "IS_MAC_ARM": True}, 16), # Apple Silicon
+ ({"IS_MACOS": True}, 14), # Intel Mac
],
)
def test_the_other_platform_totals_include_torchcodec(self, flags, total):