Skip to content

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

Studio: cap Pillow below 13 for the MLX image engine (#14802)

Daniel Han1b598dbeb0d5
diff --git a/studio/backend/core/inference/diffusion_engine_router.py b/studio/backend/core/inference/diffusion_engine_router.py
index 663415dc53c..6d47af8357b 100644
--- a/studio/backend/core/inference/diffusion_engine_router.py
+++ b/studio/backend/core/inference/diffusion_engine_router.py
@@ -395,6 +395,8 @@ def _mlx_host_refusal() -> Optional[str]:
# mflux's own darwin mlx range plus the light deps install_python_stack.py installs beside it (mflux goes in --no-deps).
_MLX_RUNTIME_REQUIREMENTS: tuple[str, ...] = (
"mlx>=0.32.0,<0.33.0",
+ # Pillow 13.0.0 breaks every mflux import (PIL._typing), so it is refused here, not at load.
+ "pillow>=12.3.0,<13",
"piexif>=1.1.3,<2",
"platformdirs>=4,<5",
"toml>=0.10.2,<1",
diff --git a/studio/backend/tests/test_diffusion_mlx_engine_router.py b/studio/backend/tests/test_diffusion_mlx_engine_router.py
index e5793ff18f0..6c6777f7c6f 100644
--- a/studio/backend/tests/test_diffusion_mlx_engine_router.py
+++ b/studio/backend/tests/test_diffusion_mlx_engine_router.py
@@ -78,6 +78,7 @@ _GOOD_VERSIONS = {
"piexif": "1.1.3",
"platformdirs": "4.3.8",
"toml": "0.10.2",
+ "pillow": "12.3.0",
}
@@ -287,6 +288,7 @@ def test_missing_runtime_falls_back(monkeypatch, mlx, mflux, needle):
({"mlx": None}, "mlx>=0.32.0,<0.33.0 (found none)"),
({"toml": None}, "toml>=0.10.2,<1 (found none)"),
({"platformdirs": "5.0.0"}, "platformdirs>=4,<5 (found 5.0.0)"),
+ ({"pillow": "13.0.0"}, "pillow>=12.3.0,<13 (found 13.0.0)"),
],
)
def test_an_incompatible_installed_runtime_falls_back(monkeypatch, versions, needle):
diff --git a/studio/install_python_stack.py b/studio/install_python_stack.py
index 9c22e16ee41..8fdc487877c 100644
--- a/studio/install_python_stack.py
+++ b/studio/install_python_stack.py
@@ -10910,8 +10910,11 @@ _MLX_NAMES: tuple[str, ...] = tuple(spec.partition("==")[0] for spec in _MLX_PIN
)
# mflux goes in --no-deps: its declared torch / transformers floors would move the MLX pins, and Z-Image
# needs only the deps below. Best-effort: a failure must never mark the MLX stack broken.
+# Pillow is capped: mflux imports PIL._typing, which in Pillow 13.0.0 needs numbers._IntegralLike,
+# absent on CPython 3.11 - 3.14, so every mflux import fails with it.
_MLX_DIFFUSION_PINS: tuple[str, ...] = ("mflux==0.22.0",)
_MLX_DIFFUSION_DEPS: tuple[str, ...] = (
+ "pillow>=12.3.0,<13",
"piexif>=1.1.3,<2",
"platformdirs>=4,<5",
"toml>=0.10.2,<1",
diff --git a/tests/studio/install/test_mlx_install.py b/tests/studio/install/test_mlx_install.py
index cd5e6d8d72a..0d864b7c5d2 100644
--- a/tests/studio/install/test_mlx_install.py
+++ b/tests/studio/install/test_mlx_install.py
@@ -488,7 +488,7 @@ def test_mlx_image_engine_pins_leave_the_mlx_stack_alone():
assert stack._MLX_PINS == ("mlx==0.32.4", "mlx-metal==0.32.4")
names = {Requirement(spec).name.lower() for spec in stack._MLX_DIFFUSION_PINS}
names |= {Requirement(spec).name.lower() for spec in stack._MLX_DIFFUSION_DEPS}
- assert names == {"mflux", "piexif", "platformdirs", "toml"}
+ assert names == {"mflux", "pillow", "piexif", "platformdirs", "toml"}
# The heavy declared deps of mflux stay out: --no-deps plus this list is the whole install.
assert not names & {
"opencv-python",