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.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
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.pyindex 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 2transformer_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.pyindex 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.pyindex 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.pyindex 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], boolreturn 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 canactually carry out."""@@ -1179,6 +1227,14 @@ def _too_old_message(pipeline_class: str, family_name: str, installed: str) -> sf"'{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.pyindex 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.txtnew file mode 100644index 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@80c7ed262aeffbeb43ef13ae04baeb9b84515a69diff --git a/studio/backend/tests/test_build_prequant_checkpoint.py b/studio/backend/tests/test_build_prequant_checkpoint.pyindex 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, accepteddiff --git a/studio/backend/tests/test_diffusion_auto_policy.py b/studio/backend/tests/test_diffusion_auto_policy.pyindex 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 teassert 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 > 0diff --git a/studio/backend/tests/test_diffusion_more_families.py b/studio/backend/tests/test_diffusion_more_families.pyindex 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_classdiff --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.tsindex 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.tsindex 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.pyindex 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 Truesatisfied = _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 nonethat 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 15if IS_WINDOWS:base_total += 1 # 8c, gated exactly as the step isif 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.pyindex 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 helperdef 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.pyindex 6a46bf872bc..434f26e84e6 100644--- a/tests/studio/install/test_diffusers_pin.py+++ b/tests/studio/install/test_diffusers_pin.py@@ -27,6 +27,11 @@ import pytestREPO_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))] = namedassert 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):continueassert 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 Falsediff --git a/tests/studio/install/test_mlx_install.py b/tests/studio/install/test_mlx_install.pyindex 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 + 2def 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.pyindex 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):