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.

Dependencies: pin pymupdf 1.28.2 on Windows ARM64, the only release with a win_arm64 wheel (#16160)

Daniel Han944886443179
diff --git a/pyproject.toml b/pyproject.toml
index 3f69594c1f6..f9b22cec777 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -168,9 +168,9 @@ studio = [
"av>=12.3.0",
# No win_arm64 wheel or sdist; RAG treats a missing sqlite_vec as unavailable.
"sqlite-vec==0.1.9 ; sys_platform != 'win32' or platform_machine != 'ARM64'",
- # Mirrors studio.txt: pymupdf publishes a win_arm64 wheel from 1.28 only.
+ # Mirrors studio.txt: pymupdf publishes a win_arm64 wheel only for 1.28.2.
"pymupdf==1.27.2.3 ; sys_platform != 'win32' or platform_machine != 'ARM64'",
- "pymupdf>=1.28.2 ; sys_platform == 'win32' and platform_machine == 'ARM64'",
+ "pymupdf==1.28.2 ; sys_platform == 'win32' and platform_machine == 'ARM64'",
"pymupdf4llm==0.3.4",
"python-docx==1.2.0",
"markdown-it-py>=3.0",
diff --git a/studio/backend/requirements/no-torch-runtime.txt b/studio/backend/requirements/no-torch-runtime.txt
index f67949870f6..b1cd985e4ab 100644
--- a/studio/backend/requirements/no-torch-runtime.txt
+++ b/studio/backend/requirements/no-torch-runtime.txt
@@ -112,9 +112,9 @@ pillow==11.3.0; python_version < "3.10"
# sqlite-vec publishes win_amd64 only and no sdist; the RAG store treats a missing sqlite_vec as
# "RAG unavailable". Same marker as studio.txt: this file is installed directly on an update.
sqlite-vec==0.1.9; sys_platform != "win32" or platform_machine != "ARM64"
-# pymupdf publishes a win_arm64 wheel from 1.28 only.
+# pymupdf publishes a win_arm64 wheel only for 1.28.2 (2.0 has none, so ">=" builds MuPDF from source).
pymupdf==1.27.2.3; sys_platform != "win32" or platform_machine != "ARM64"
-pymupdf>=1.28.2; sys_platform == "win32" and platform_machine == "ARM64"
+pymupdf==1.28.2; sys_platform == "win32" and platform_machine == "ARM64"
# 0.3.x keeps pymupdf-layout (which pulls onnxruntime) an optional extra; the
# lockstep 1.27.x line makes it a hard dep we do not need for to_markdown().
pymupdf4llm==0.3.4
diff --git a/studio/backend/requirements/studio.txt b/studio/backend/requirements/studio.txt
index 2667a697c9a..a1ebc3979f5 100644
--- a/studio/backend/requirements/studio.txt
+++ b/studio/backend/requirements/studio.txt
@@ -66,9 +66,9 @@ av>=12.3.0
# sqlite-vec publishes win_amd64 only and no sdist, so there is nothing to floor to. The RAG
# store treats a missing sqlite_vec as "RAG unavailable".
sqlite-vec==0.1.9; sys_platform != "win32" or platform_machine != "ARM64"
-# pymupdf publishes a win_arm64 wheel from 1.28 only.
+# pymupdf publishes a win_arm64 wheel only for 1.28.2 (2.0 has none, so ">=" builds MuPDF from source).
pymupdf==1.27.2.3; sys_platform != "win32" or platform_machine != "ARM64"
-pymupdf>=1.28.2; sys_platform == "win32" and platform_machine == "ARM64"
+pymupdf==1.28.2; sys_platform == "win32" and platform_machine == "ARM64"
# 0.3.x keeps pymupdf-layout (which pulls onnxruntime) an optional extra; the
# lockstep 1.27.x line makes it a hard dep we do not need for to_markdown().
pymupdf4llm==0.3.4
diff --git a/tests/studio/install/test_pymupdf_platform_pins.py b/tests/studio/install/test_pymupdf_platform_pins.py
new file mode 100644
index 00000000000..38f3fc91acd
--- /dev/null
+++ b/tests/studio/install/test_pymupdf_platform_pins.py
@@ -0,0 +1,75 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""pymupdf ships wheels for a few platforms per release (2.0 has no win_arm64 one), so a lower bound alone can
+resolve to a release that only has an sdist and build MuPDF from source. Every platform gets one exact pin,
+the same in every file that installs it."""
+
+from __future__ import annotations
+
+import pathlib
+import tomllib
+
+import pytest
+from packaging.requirements import Requirement
+
+REPO_ROOT = pathlib.Path(__file__).resolve().parents[3]
+REQ_ROOT = REPO_ROOT / "studio" / "backend" / "requirements"
+
+PLATFORMS = {
+ "win_arm64": {"sys_platform": "win32", "platform_machine": "ARM64"},
+ "win_amd64": {"sys_platform": "win32", "platform_machine": "AMD64"},
+ "linux_x86_64": {"sys_platform": "linux", "platform_machine": "x86_64"},
+ "linux_aarch64": {"sys_platform": "linux", "platform_machine": "aarch64"},
+ "macos_arm64": {"sys_platform": "darwin", "platform_machine": "arm64"},
+}
+
+
+def _requirement_files():
+ for name in ("studio.txt", "no-torch-runtime.txt"):
+ path = REQ_ROOT / name
+ lines = path.read_text(encoding = "utf-8").splitlines()
+ yield (
+ name,
+ [
+ line.split(" #")[0].strip()
+ for line in lines
+ if line.strip() and not line.startswith("#")
+ ],
+ )
+ project = tomllib.loads((REPO_ROOT / "pyproject.toml").read_text(encoding = "utf-8"))["project"]
+ yield "pyproject.toml [studio]", list(project["optional-dependencies"]["studio"])
+
+
+def _pymupdf_for(lines, environment):
+ env = {"python_version": "3.12", "python_full_version": "3.12.0", **environment}
+ found = []
+ for line in lines:
+ requirement = Requirement(line)
+ if requirement.name.lower() != "pymupdf":
+ continue
+ if requirement.marker is None or requirement.marker.evaluate(env):
+ found.append(requirement)
+ return found
+
+
[email protected]("platform", sorted(PLATFORMS))
+def test_every_file_pins_one_exact_pymupdf_per_platform(platform):
+ pins = {}
+ for source, lines in _requirement_files():
+ found = _pymupdf_for(lines, PLATFORMS[platform])
+ assert len(found) == 1, (source, platform, [str(r) for r in found])
+ specifiers = list(found[0].specifier)
+ assert len(specifiers) == 1 and specifiers[0].operator == "==", (
+ f"{source} lets {platform} resolve pymupdf {found[0].specifier}: a newer release without a "
+ f"{platform} wheel would build MuPDF from source. Pin it with ==."
+ )
+ pins[source] = specifiers[0].version
+ assert len(set(pins.values())) == 1, (platform, pins)
+
+
+def test_win_arm64_stays_on_the_release_that_has_its_wheel():
+ # 1.28.2 is the only pymupdf release with a win_arm64 wheel; 1.27.x and 2.0 have none.
+ for source, lines in _requirement_files():
+ (requirement,) = _pymupdf_for(lines, PLATFORMS["win_arm64"])
+ assert str(requirement.specifier) == "==1.28.2", (source, str(requirement))