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.

Desktop: build and ship a native Windows ARM64 installer (#11122)

Daniel Han97730eb807a6
diff --git a/.github/workflows/release-desktop.yml b/.github/workflows/release-desktop.yml
index 9bfb04e1f49..1b6c1c0de7a 100644
--- a/.github/workflows/release-desktop.yml
+++ b/.github/workflows/release-desktop.yml
@@ -39,7 +39,7 @@ env:
Desktop app for Unsloth.
**macOS**: Download `Unsloth-Desktop-MacOS.dmg` (Apple Silicon).
- **Windows**: Download `Unsloth-Desktop-Windows.exe`.
+ **Windows**: Download `Unsloth-Desktop-Windows.exe`, or `Unsloth-Desktop-Windows-ARM64.exe` on a Windows on ARM machine.
**Linux**: Download `Unsloth-Desktop-Ubuntu.deb` for Ubuntu/Debian. `.AppImage` is experimental.
> Linux in-app updates are AppImage-oriented. Package installs should update by downloading a new package.
@@ -504,6 +504,15 @@ jobs:
args: ''
label: Windows (x64)
artifact: windows-x64
+ # Cross-compiled from the same x64 runner: there is no ARM64 Windows
+ # runner, and Tauri builds aarch64-pc-windows-msvc from x64 the way
+ # the macOS leg builds aarch64-apple-darwin. NSIS is the only Windows
+ # bundle target configured, which is the one that supports ARM64 (WiX
+ # does not), so nothing in bundle.targets needs an exception here.
+ - platform: windows-latest
+ args: '--target aarch64-pc-windows-msvc'
+ label: Windows (ARM64)
+ artifact: windows-arm64
name: Build ${{ matrix.label }}
needs: prepare-version
@@ -716,7 +725,9 @@ jobs:
- name: Install Rust stable
uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable @ 2026-03-27
with:
- targets: ${{ matrix.platform == 'macos-latest' && 'aarch64-apple-darwin,x86_64-apple-darwin' || '' }}
+ # macOS installs both slices; the Windows ARM64 leg needs the cross target
+ # installed or cargo fails with "target may not be installed".
+ targets: ${{ matrix.platform == 'macos-latest' && 'aarch64-apple-darwin,x86_64-apple-darwin' || (matrix.artifact == 'windows-arm64' && 'aarch64-pc-windows-msvc' || '') }}
- name: Patch desktop app version
shell: bash
@@ -1614,6 +1625,11 @@ jobs:
shell: bash
env:
ARTIFACT_PATHS: ${{ steps.build_linux.outputs.artifactPaths || steps.build_macos.outputs.artifactPaths || steps.build_windows.outputs.artifactPaths }}
+ # Both Windows legs emit a -setup.exe, and publish-release merges every
+ # leg's artifact into one directory, so the two must not stage the same
+ # name. x64 keeps the historical name; anything else would break every
+ # published download link and the updater entry that points at it.
+ MATRIX_ARTIFACT: ${{ matrix.artifact }}
run: |
set -euo pipefail
if command -v python3 >/dev/null 2>&1; then
@@ -1639,13 +1655,18 @@ jobs:
destination = pathlib.Path(os.environ['RUNNER_TEMP'], 'desktop-release-assets')
destination.mkdir(parents=True, exist_ok=True)
base_name = 'Unsloth-Desktop'
+ windows_name = (
+ f'{base_name}-Windows-ARM64'
+ if os.environ.get('MATRIX_ARTIFACT') == 'windows-arm64'
+ else f'{base_name}-Windows'
+ )
suffix_names = (
('.app.tar.gz.sig', f'{base_name}-ARM64.app.tar.gz.sig'),
('.app.tar.gz', f'{base_name}-ARM64.app.tar.gz'),
('.AppImage.sig', f'{base_name}-Linux.AppImage.sig'),
('.AppImage', f'{base_name}-Linux.AppImage'),
- ('-setup.exe.sig', f'{base_name}-Windows.exe.sig'),
- ('-setup.exe', f'{base_name}-Windows.exe'),
+ ('-setup.exe.sig', f'{windows_name}.exe.sig'),
+ ('-setup.exe', f'{windows_name}.exe'),
('.dmg', f'{base_name}-MacOS.dmg'),
('.deb', f'{base_name}-Ubuntu.deb'),
)
@@ -1721,7 +1742,7 @@ jobs:
set -uo pipefail
# The three matrix legs, by their `name:` (Build <matrix.label>).
- LEGS=('Build macOS (Apple Silicon)' 'Build Linux (x64)' 'Build Windows (x64)')
+ LEGS=('Build macOS (Apple Silicon)' 'Build Linux (x64)' 'Build Windows (x64)' 'Build Windows (ARM64)')
POLL=30
DEADLINE=$(( $(date +%s) + 75 * 60 ))
# Matrix job records appear with the run, so a leg still missing well
@@ -1818,6 +1839,8 @@ jobs:
f'{base_name}-Ubuntu.deb',
f'{base_name}-Windows.exe',
f'{base_name}-Windows.exe.sig',
+ f'{base_name}-Windows-ARM64.exe',
+ f'{base_name}-Windows-ARM64.exe.sig',
}
actual_names = {path.name for path in files}
if actual_names != expected_names:
@@ -1933,7 +1956,11 @@ jobs:
darwin = entry('.app.tar.gz.sig')
linux = entry('.AppImage.sig')
- windows = entry('.exe.sig')
+ # Both Windows bundles end in .exe.sig, and exactly_one() refuses an ambiguous
+ # match, so name them in full. -Windows.exe.sig does not match -Windows-ARM64.exe.sig
+ # under endswith, which is what keeps the two entries distinct.
+ windows = entry('-Windows.exe.sig')
+ windows_arm64 = entry('-Windows-ARM64.exe.sig')
notes = pathlib.Path(os.environ['RUNNER_TEMP'], 'desktop-release-notes.md').read_text()
metadata = {
'version': os.environ['APP_VERSION'],
@@ -1948,6 +1975,11 @@ jobs:
'linux-x86_64-appimage': linux,
'windows-x86_64': windows,
'windows-x86_64-nsis': windows,
+ # Tauri asks for {os}-{arch}; without these an ARM64 install either
+ # finds no entry and never updates, or takes the x86_64 one and
+ # replaces a native install with an emulated build.
+ 'windows-aarch64': windows_arm64,
+ 'windows-aarch64-nsis': windows_arm64,
},
}
output = pathlib.Path(os.environ['RUNNER_TEMP'], 'latest.json')
@@ -2039,6 +2071,7 @@ jobs:
'darwin-aarch64': False,
'linux-x86_64': False,
'windows-x86_64': False,
+ 'windows-aarch64': False,
}
expected_prefix = f'https://github.com/{os.environ["GITHUB_REPOSITORY"]}/releases/download/{release_tag}/'
forbidden_fragments = ('/releases/latest/', '/releases/download/desktop-latest/')
@@ -2163,6 +2196,7 @@ jobs:
'Unsloth-Desktop-Linux.AppImage',
'Unsloth-Desktop-Ubuntu.deb',
'Unsloth-Desktop-Windows.exe',
+ 'Unsloth-Desktop-Windows-ARM64.exe',
}
missing = sorted(required - names)
if missing:
diff --git a/tests/security/test_release_desktop_integrity.py b/tests/security/test_release_desktop_integrity.py
index 6756b1e94ad..0562a6e1619 100644
--- a/tests/security/test_release_desktop_integrity.py
+++ b/tests/security/test_release_desktop_integrity.py
@@ -3,6 +3,7 @@
from __future__ import annotations
import base64
+import json
import os
import subprocess
from pathlib import Path
@@ -164,6 +165,8 @@ def _stage_assets(tmp_path: Path) -> None:
("Unsloth-Desktop-Linux.AppImage.sig", signature),
("Unsloth-Desktop-Windows.exe", b"installer"),
("Unsloth-Desktop-Windows.exe.sig", signature),
+ ("Unsloth-Desktop-Windows-ARM64.exe", b"arm64 installer"),
+ ("Unsloth-Desktop-Windows-ARM64.exe.sig", signature),
):
(asset_dir / name).write_bytes(payload)
@@ -342,6 +345,125 @@ def test_the_publish_sequence_never_rewrites_the_release_body(tmp_path):
assert "Desktop app for Unsloth." in notes
+def test_the_build_matrix_covers_windows_on_arm():
+ """The leg has to exist, cross-compile from the x64 runner (there is no ARM64
+ Windows runner), have its Rust target installed, and be named in the publish
+ gate. A leg the gate does not name can fail while the release still publishes."""
+ workflow = _workflow()
+ include = workflow["jobs"]["build"]["strategy"]["matrix"]["include"]
+ arm64 = [entry for entry in include if entry.get("artifact") == "windows-arm64"]
+ assert len(arm64) == 1, f"expected one Windows ARM64 leg, got {arm64}"
+ leg = arm64[0]
+ assert leg["platform"] == "windows-latest"
+ assert "--target aarch64-pc-windows-msvc" in leg["args"]
+ assert leg["label"] == "Windows (ARM64)"
+
+ rust = _step(workflow, "build", "Install Rust stable")
+ assert "aarch64-pc-windows-msvc" in rust["with"]["targets"]
+
+ wait = _step(workflow, "publish-release", "Wait for the build matrix")["run"]
+ assert f"'Build {leg['label']}'" in wait
+
+
+def _stage_windows_leg(workflow, tmp_path: Path, artifact: str) -> list[str]:
+ """Run the real "Stage release assets" step for one Windows leg and return what it staged."""
+ bundles = tmp_path / f"bundles-{artifact}"
+ bundles.mkdir(parents = True, exist_ok = True)
+ # Tauri names the NSIS output per target; both end in -setup.exe, which is the
+ # whole point of this test.
+ arch = "arm64" if artifact == "windows-arm64" else "x64"
+ installer = bundles / f"Unsloth Studio_0.1.50_{arch}-setup.exe"
+ installer.write_bytes(b"installer")
+ signature = bundles / f"Unsloth Studio_0.1.50_{arch}-setup.exe.sig"
+ signature.write_text("signature", encoding = "utf-8")
+
+ staged = tmp_path / "desktop-release-assets"
+ if staged.exists():
+ for path in staged.iterdir():
+ path.unlink()
+
+ result = _run_step(
+ workflow,
+ "build",
+ "Stage release assets",
+ tmp_path,
+ extra_env = {
+ "ARTIFACT_PATHS": json.dumps([str(installer), str(signature)]),
+ "MATRIX_ARTIFACT": artifact,
+ },
+ )[0]
+ assert result.returncode == 0, result.stderr
+ return sorted(path.name for path in staged.iterdir())
+
+
+def test_the_two_windows_legs_never_stage_the_same_asset_name(tmp_path):
+ """publish-release downloads every leg's artifact into one directory with
+ merge-multiple, so if both Windows legs staged Unsloth-Desktop-Windows.exe one
+ would silently overwrite the other and the release would ship one architecture
+ twice. The x64 name is also load bearing: it is the published download link."""
+ workflow = _workflow()
+ x64 = _stage_windows_leg(workflow, tmp_path, "windows-x64")
+ arm64 = _stage_windows_leg(workflow, tmp_path, "windows-arm64")
+
+ assert x64 == ["Unsloth-Desktop-Windows.exe", "Unsloth-Desktop-Windows.exe.sig"]
+ assert arm64 == [
+ "Unsloth-Desktop-Windows-ARM64.exe",
+ "Unsloth-Desktop-Windows-ARM64.exe.sig",
+ ]
+ assert not set(x64) & set(arm64)
+
+
+def test_no_matrix_leg_shares_a_fixed_artifact_name_with_another(tmp_path):
+ """upload-artifact v4 and later refuse a duplicate name within a run, so a step with a
+ literal name that more than one leg reaches fails the second leg outright and takes the
+ release with it. Two Windows legs on the same `windows-latest` platform make
+ `matrix.platform` too coarse to gate such a step; only `matrix.artifact` is unique.
+ """
+ workflow = _workflow()
+ legs = {
+ entry["artifact"] for entry in workflow["jobs"]["build"]["strategy"]["matrix"]["include"]
+ }
+
+ for step in workflow["jobs"]["build"]["steps"]:
+ if "upload-artifact" not in step.get("uses", ""):
+ continue
+ name = step.get("with", {}).get("name", "")
+ if "matrix.artifact" in name:
+ continue # already unique per leg
+ condition = step.get("if", "")
+ pinned = [leg for leg in legs if f"matrix.artifact == '{leg}'" in condition]
+ assert len(pinned) == 1, (
+ f"step {step.get('name')!r} uploads the fixed name {name!r} but is gated on "
+ f"{condition!r}, which is not pinned to exactly one matrix leg"
+ )
+
+
+def test_the_updater_manifest_points_windows_arm64_at_its_own_bundle(tmp_path):
+ """Tauri looks an update up by {os}-{arch}. Without a windows-aarch64 entry an
+ ARM64 install either never sees an update, or takes the x86_64 one and replaces a
+ native install with an emulated build. Both Windows bundles end in .exe.sig, so
+ this also pins the selection: the two entries must not collapse onto one file."""
+ workflow = _workflow()
+ result, _ = _run_create_release(workflow, tmp_path)
+ assert result.returncode == 0, result.stderr
+
+ metadata = yaml.safe_load((tmp_path / "latest.json").read_text(encoding = "utf-8"))
+ platforms = metadata["platforms"]
+ for key in ("windows-x86_64", "windows-x86_64-nsis", "windows-aarch64", "windows-aarch64-nsis"):
+ assert key in platforms, f"latest.json is missing {key}"
+
+ arm64_url = platforms["windows-aarch64"]["url"]
+ x64_url = platforms["windows-x86_64"]["url"]
+ assert arm64_url.endswith("Unsloth-Desktop-Windows-ARM64.exe"), arm64_url
+ assert x64_url.endswith("Unsloth-Desktop-Windows.exe"), x64_url
+ assert "ARM64" not in x64_url, "the x64 entry picked up the ARM64 bundle"
+ assert arm64_url != x64_url
+ # The -nsis aliases exist because Tauri appends the installer kind; they must
+ # resolve to the same bundle as the bare key or an update can cross architectures.
+ assert platforms["windows-aarch64-nsis"] == platforms["windows-aarch64"]
+ assert platforms["windows-x86_64-nsis"] == platforms["windows-x86_64"]
+
+
def test_release_uploads_never_clobber_or_mutate_the_legacy_channel():
uploads = _upload_commands(_workflow())
versioned = [line for line in uploads if "$DESKTOP_RELEASE_TAG" in line]
diff --git a/tests/security/test_release_desktop_permissions.py b/tests/security/test_release_desktop_permissions.py
index e1ffa45649c..ea7616b975b 100644
--- a/tests/security/test_release_desktop_permissions.py
+++ b/tests/security/test_release_desktop_permissions.py
@@ -103,7 +103,15 @@ def test_build_matrix_hands_off_assets_without_release_credentials():
wait_run = wait["run"]
matrix_legs = {f"Build {entry['label']}" for entry in build["strategy"]["matrix"]["include"]}
- assert len(matrix_legs) == len(tauri_steps)
+ # Legs outnumber the tauri-action steps: the two Windows legs (x64 and the
+ # cross-compiled ARM64) share one `build_windows` step and differ only by
+ # matrix.args. What matters is that every leg is named in the wait list, which
+ # the loop below asserts, and that every build step is still reachable from
+ # some leg's platform.
+ assert len(matrix_legs) >= len(tauri_steps)
+ leg_platforms = {entry["platform"] for entry in build["strategy"]["matrix"]["include"]}
+ for step in tauri_steps:
+ assert any(platform in step.get("if", "") for platform in leg_platforms), step.get("name")
for leg in matrix_legs:
assert f"'{leg}'" in wait_run, leg
diff --git a/tests/studio/install/test_dependency_pass_skips.py b/tests/studio/install/test_dependency_pass_skips.py
index 27d54bdc0f9..6f1756a4aa8 100644
--- a/tests/studio/install/test_dependency_pass_skips.py
+++ b/tests/studio/install/test_dependency_pass_skips.py
@@ -1478,9 +1478,7 @@ def test_the_fingerprint_names_everything_a_verdict_depends_on(monkeypatch) -> N
fingerprint = stack._mlx_health_fingerprint()
# The narrowed mlx-vlm range, not the static one: the installed zoo is part of what a
# recorded verdict is valid for, so changing the zoo must invalidate it.
- assert fingerprint["pins"] == list(stack._MLX_PINS) + [
- stack._mlx_vlm_spec_for_installed_zoo()
- ]
+ assert fingerprint["pins"] == list(stack._MLX_PINS) + [stack._mlx_vlm_spec_for_installed_zoo()]
assert fingerprint["pins"][-1].startswith(stack._MLX_VLM_SPEC)
assert fingerprint["python"] == stack._installer_python_tag()
assert fingerprint["imports"] == {n: "0.4.5" for n in stack._MLX_IMPORTED_DEPENDENCIES}
diff --git a/tests/studio/install/test_mlx_install.py b/tests/studio/install/test_mlx_install.py
index a906c82be63..15447fc4ab8 100644
--- a/tests/studio/install/test_mlx_install.py
+++ b/tests/studio/install/test_mlx_install.py
@@ -355,9 +355,7 @@ def test_the_core_phase_upgrading_the_zoo_re_resolves_mlx(monkeypatch):
narrow = f"{stack._MLX_VLM_SPEC},<0.7.0"
# Twice for the install step, then the widened answer after the core phase.
_zoo_spec_sequence(monkeypatch, [narrow, narrow, stack._MLX_VLM_SPEC])
- calls = _run_to_extras(
- monkeypatch, platform = "macos_arm", skip_base = False, no_torch = False
- )
+ calls = _run_to_extras(monkeypatch, platform = "macos_arm", skip_base = False, no_torch = False)
assert len(calls) == 2
assert "MLX stack (re-resolved for the new zoo)" in _run_to_extras.steps
assert narrow in list(calls[0].args[1:])
@@ -366,8 +364,6 @@ def test_the_core_phase_upgrading_the_zoo_re_resolves_mlx(monkeypatch):
def test_an_unchanged_zoo_does_not_re_resolve_mlx(monkeypatch):
_zoo_spec_sequence(monkeypatch, [stack._MLX_VLM_SPEC])
- calls = _run_to_extras(
- monkeypatch, platform = "macos_arm", skip_base = False, no_torch = False
- )
+ calls = _run_to_extras(monkeypatch, platform = "macos_arm", skip_base = False, no_torch = False)
assert len(calls) == 1
assert "MLX stack (zoo unchanged, skipped)" in _run_to_extras.steps
diff --git a/tests/studio/test_tauri_branding_contract.py b/tests/studio/test_tauri_branding_contract.py
index 95cf652775b..280126ecf85 100644
--- a/tests/studio/test_tauri_branding_contract.py
+++ b/tests/studio/test_tauri_branding_contract.py
@@ -185,6 +185,8 @@ def test_desktop_release_asset_names_are_human_readable() -> None:
"Ubuntu.deb",
"Windows.exe",
"Windows.exe.sig",
+ "Windows-ARM64.exe",
+ "Windows-ARM64.exe.sig",
}
for suffix in expected_suffixes:
assert f"f'{{base_name}}-{suffix}'" in workflow
@@ -194,6 +196,7 @@ def test_desktop_release_asset_names_are_human_readable() -> None:
"Unsloth-Desktop-Linux.AppImage",
"Unsloth-Desktop-Ubuntu.deb",
"Unsloth-Desktop-Windows.exe",
+ "Unsloth-Desktop-Windows-ARM64.exe",
):
assert name in workflow