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.

Use tar.xz for Node downloads on macOS and Linux (#16253)

Nilay9eeee2c16954
diff --git a/scripts/update_node_pins.py b/scripts/update_node_pins.py
index ef1869f70c4..a8e605ac777 100644
--- a/scripts/update_node_pins.py
+++ b/scripts/update_node_pins.py
@@ -37,9 +37,13 @@ _CHUNK = 1 << 20
def archive_names(version: str) -> list[str]:
return [
f"node-v{version}-linux-x64.tar.gz",
+ f"node-v{version}-linux-x64.tar.xz",
f"node-v{version}-linux-arm64.tar.gz",
+ f"node-v{version}-linux-arm64.tar.xz",
f"node-v{version}-darwin-x64.tar.gz",
+ f"node-v{version}-darwin-x64.tar.xz",
f"node-v{version}-darwin-arm64.tar.gz",
+ f"node-v{version}-darwin-arm64.tar.xz",
f"node-v{version}-win-x64.zip",
f"node-v{version}-win-arm64.zip",
]
diff --git a/studio/NODE_RUNTIME.md b/studio/NODE_RUNTIME.md
index cd675e089a2..ed0c68ae250 100644
--- a/studio/NODE_RUNTIME.md
+++ b/studio/NODE_RUNTIME.md
@@ -42,8 +42,9 @@ For a manual update or a new major:
and the selected release's notes, including security fixes.
2. Fetch its `SHASUMS256.txt` and signature from `https://nodejs.org/dist/v<version>/`.
Verify the signature with the [Node release keys](https://github.com/nodejs/release-keys).
-3. Update `default_version` and all six archive digests together: Linux and macOS
- x64/ARM64 `.tar.gz` files and Windows x64/ARM64 `.zip` files. Download the
+3. Update `default_version` and all ten archive digests together: Linux and macOS
+ x64/ARM64 `.tar.xz` and `.tar.gz` files (`.tar.gz` serves Pythons without
+ `lzma`) and Windows x64/ARM64 `.zip` files. Download the
archives and verify their digests before committing the pins.
4. Run the Node installer/runtime tests, both platforms' Node selection tests,
and setup rerun tests. Check an upgrade from the previous pin, a second run
diff --git a/studio/install_node_prebuilt.py b/studio/install_node_prebuilt.py
index cf845a4e730..8885e50bdf4 100644
--- a/studio/install_node_prebuilt.py
+++ b/studio/install_node_prebuilt.py
@@ -114,6 +114,19 @@ class HostInfo:
is_windows: bool
+def tar_archive_ext() -> str:
+ # Import, not find_spec: lzma.py exists even when _lzma was not built.
+ try:
+ import lzma # noqa: F401
+ except ImportError:
+ return ".tar.gz"
+ return ".tar.xz"
+
+
+def gzip_alternative(asset: str) -> str:
+ return asset[: -len(".tar.xz")] + ".tar.gz" if asset.endswith(".tar.xz") else asset
+
+
def detect_host() -> HostInfo:
system = platform.system()
machine = platform.machine().lower()
@@ -136,8 +149,7 @@ def detect_host() -> HostInfo:
# Node 24 ships no linux-armv7l build.
raise PrebuiltFallback(f"unsupported CPU architecture for Node prebuilt: {machine}")
- # Not .tar.xz so the extractor needs no xz.
- archive_ext = ".zip" if is_windows else ".tar.gz"
+ archive_ext = ".zip" if is_windows else tar_archive_ext()
return HostInfo(
system = system,
machine = machine,
@@ -422,7 +434,7 @@ def resolve_expected_sha256(pins: dict, version: str, asset: str, *, allow_unver
return expected
-# ── Safe archive extraction (zip + tar.gz, traversal/symlink guarded) ──
+# ── Safe archive extraction (zip + tar.gz + tar.xz, traversal/symlink guarded) ──
def _safe_extract_path(base: Path, member_name: str) -> Path:
member_path = Path(member_name.replace("\\", "/"))
if member_path.is_absolute():
@@ -453,7 +465,7 @@ def _extract_zip_safely(source: Path, base: Path) -> None:
def _extract_tar_safely(source: Path, base: Path) -> None:
# bin/npm, npx, corepack are relative symlinks into lib/node_modules; resolve after files.
pending_links: list[tuple[tarfile.TarInfo, Path]] = []
- with tarfile.open(source, "r:gz") as archive:
+ with tarfile.open(source, "r:*") as archive:
for member in archive.getmembers():
target = _safe_extract_path(base, member.name)
if member.isdir():
@@ -501,7 +513,7 @@ def extract_archive(archive_path: Path, destination: Path) -> None:
destination.mkdir(parents = True, exist_ok = True)
if archive_path.name.endswith(".zip"):
_extract_zip_safely(archive_path, destination)
- elif archive_path.name.endswith(".tar.gz"):
+ elif archive_path.name.endswith((".tar.gz", ".tar.xz")):
_extract_tar_safely(archive_path, destination)
else:
raise PrebuiltFallback(f"unsupported archive format: {archive_path.name}")
@@ -914,6 +926,27 @@ def _record_runtime_verification_under_lock(
return True
+def pin_to_keep(pins: dict, version: str, asset: str, install_dir: Path) -> str | None:
+ """Pin of the recorded archive when it is the same Node build in another format, so a format switch does not re-download."""
+ recorded = (load_metadata(install_dir) or {}).get("asset")
+ stem = gzip_alternative(asset)[: -len(".tar.gz")] if ".tar." in asset else None
+ if stem and recorded in (stem + ".tar.gz", stem + ".tar.xz"):
+ return pinned_sha256(pins, version, recorded) or pinned_sha256(pins, version, asset)
+ return pinned_sha256(pins, version, asset)
+
+
+def _download_asset(staging: Path, version: str, asset: str, expected_sha: str) -> Path:
+ archive_path = staging / asset
+ log(f"downloading {node_download_url(version, asset)}")
+ download_file_verified(
+ node_download_url(version, asset),
+ archive_path,
+ expected_sha256 = expected_sha,
+ label = asset,
+ )
+ return archive_path
+
+
def existing_install_matches(
install_dir: Path,
host: HostInfo,
@@ -1099,7 +1132,7 @@ def install_prebuilt(install_dir: Path, *, channel: str, min_major: int, force:
log(f"target Node v{version} ({asset})")
# Keep an existing install only if it matches the pin (or pinning is opted out).
- pin = pinned_sha256(pins, version, asset)
+ pin = pin_to_keep(pins, version, asset, install_dir)
allow_unverified = allow_unverified_node()
may_keep = pin is not None or allow_unverified
@@ -1112,6 +1145,9 @@ def install_prebuilt(install_dir: Path, *, channel: str, min_major: int, force:
return EXIT_SUCCESS
with install_lock(install_lock_path(install_dir)):
+ # Another installer may have switched archive format while we waited.
+ pin = pin_to_keep(pins, version, asset, install_dir)
+ may_keep = pin is not None or allow_unverified
if (
not force
and may_keep
@@ -1131,14 +1167,18 @@ def install_prebuilt(install_dir: Path, *, channel: str, min_major: int, force:
staging_root.mkdir(parents = True, exist_ok = True)
staging = make_staging_dir(staging_root, f"{install_dir.name}.staging-")
try:
- archive_path = staging / asset
- log(f"downloading {node_download_url(version, asset)}")
- download_file_verified(
- node_download_url(version, asset),
- archive_path,
- expected_sha256 = expected_sha,
- label = asset,
- )
+ try:
+ archive_path = _download_asset(staging, version, asset, expected_sha)
+ except Exception as exc: # noqa: BLE001
+ # A mirror may carry only .tar.gz.
+ if gzip_alternative(asset) == asset:
+ raise
+ log(f"{asset} unavailable ({exc}); trying {gzip_alternative(asset)}")
+ asset = gzip_alternative(asset)
+ expected_sha = resolve_expected_sha256(
+ pins, version, asset, allow_unverified = allow_unverified
+ )
+ archive_path = _download_asset(staging, version, asset, expected_sha)
extract_dir = staging / "extracted"
extract_archive(archive_path, extract_dir)
diff --git a/studio/node_prebuilt_pins.json b/studio/node_prebuilt_pins.json
index 18932608567..9d077b19200 100644
--- a/studio/node_prebuilt_pins.json
+++ b/studio/node_prebuilt_pins.json
@@ -5,9 +5,13 @@
"versions": {
"24.22.2": {
"node-v24.22.2-linux-x64.tar.gz": "361718c444e49af2ca5a110c83ba6a8901143f23ab285ebbef0341f391f482a9",
+ "node-v24.22.2-linux-x64.tar.xz": "48cc0e21e048790e54c0cf5749c2725005313d652651c40b7a21feb9697aaf75",
"node-v24.22.2-linux-arm64.tar.gz": "95c264150aceb7f3437a29fd6984924f5f8d1511ea3cbd6c508b83f6c555dae2",
+ "node-v24.22.2-linux-arm64.tar.xz": "eb187837a2230d4047161ac0be008584e16b46f726e9c9490ee35dc6b17d9ba8",
"node-v24.22.2-darwin-x64.tar.gz": "d5e336d588c45be0c37dbd52cc29895593009ca4997a77a1fd02815131ed0e52",
+ "node-v24.22.2-darwin-x64.tar.xz": "6965578fd823e72c1b5387f5ab84cb25368f886e02eb8779e6f0fce6b91c27b7",
"node-v24.22.2-darwin-arm64.tar.gz": "aa9549349e47dffaa42dcf95d6e06ade8c4bdafc980979883b88767670df385a",
+ "node-v24.22.2-darwin-arm64.tar.xz": "1f5ac075be50bed4780ea3be19a007fda95ea4d527d28d76d0b91de47d915115",
"node-v24.22.2-win-x64.zip": "ca1bff5d8ead13c9f2ea404a176db46bd430704d5b5113734049fa365e7799e2",
"node-v24.22.2-win-arm64.zip": "f47968c213105077f64c6510f007632c0ca2574802a0b5067c327c49abe1c468"
}
diff --git a/tests/studio/install/test_install_node_prebuilt_logic.py b/tests/studio/install/test_install_node_prebuilt_logic.py
index 83d1eee3ccf..7183498e26f 100644
--- a/tests/studio/install/test_install_node_prebuilt_logic.py
+++ b/tests/studio/install/test_install_node_prebuilt_logic.py
@@ -3,6 +3,7 @@
import importlib.util
import io
import contextlib
+import dataclasses
import json
import os
import sys
@@ -69,10 +70,10 @@ def _host(node_os: str, node_arch: str) -> HostInfo:
@pytest.mark.parametrize(
"system,machine,exp_os,exp_arch,exp_ext",
[
- ("Linux", "x86_64", "linux", "x64", ".tar.gz"),
- ("Linux", "aarch64", "linux", "arm64", ".tar.gz"),
- ("Darwin", "x86_64", "darwin", "x64", ".tar.gz"),
- ("Darwin", "arm64", "darwin", "arm64", ".tar.gz"),
+ ("Linux", "x86_64", "linux", "x64", ".tar.xz"),
+ ("Linux", "aarch64", "linux", "arm64", ".tar.xz"),
+ ("Darwin", "x86_64", "darwin", "x64", ".tar.xz"),
+ ("Darwin", "arm64", "darwin", "arm64", ".tar.xz"),
("Windows", "AMD64", "win", "x64", ".zip"),
("Windows", "ARM64", "win", "arm64", ".zip"),
],
@@ -1656,3 +1657,106 @@ def test_swap_into_place_reports_the_managed_parent_when_aside_is_denied(
parent_takeown = f'takeown /F "{install_dir.parent}"'
assert any(parent_takeown in line for line in recovery), recovery
assert not any(parent_takeown in line and " /R " in line for line in recovery), recovery
+
+
+def test_detect_host_without_lzma_keeps_tar_gz(monkeypatch):
+ monkeypatch.setattr(M.platform, "system", lambda: "Linux")
+ monkeypatch.setattr(M.platform, "machine", lambda: "x86_64")
+ monkeypatch.delitem(sys.modules, "lzma", raising = False)
+ monkeypatch.setitem(sys.modules, "_lzma", None)
+ assert M.detect_host().archive_ext == ".tar.gz"
+
+
+def test_every_pinned_tar_gz_has_a_tar_xz():
+ for assets in M.load_pins()["versions"].values():
+ for name in assets:
+ if name.endswith(".tar.gz"):
+ assert name.replace(".tar.gz", ".tar.xz") in assets
+
+
+def test_extract_tar_xz(tmp_path):
+ root = tmp_path / "src" / "node"
+ (root / "bin").mkdir(parents = True)
+ (root / "bin" / "node").write_text("x")
+ archive = tmp_path / "node.tar.xz"
+ with tarfile.open(archive, "w:xz") as tar:
+ tar.add(root, arcname = "node")
+ M.extract_archive(archive, tmp_path / "out")
+ assert (tmp_path / "out" / "node" / "bin" / "node").read_text() == "x"
+
+
+def test_tar_gz_install_is_kept_after_the_switch_to_tar_xz(tmp_path, monkeypatch):
+ pins = {
+ "versions": {
+ "1.0.0": {
+ "node-v1.0.0-linux-x64.tar.gz": "a" * 64,
+ "node-v1.0.0-linux-x64.tar.xz": "b" * 64,
+ "node-v1.0.0-linux-arm64.tar.gz": "c" * 64,
+ }
+ }
+ }
+ asset = "node-v1.0.0-linux-x64.tar.xz"
+ monkeypatch.setattr(M, "load_metadata", lambda d: {"asset": "node-v1.0.0-linux-x64.tar.gz"})
+ assert M.pin_to_keep(pins, "1.0.0", asset, tmp_path) == "a" * 64
+ monkeypatch.setattr(M, "load_metadata", lambda d: {"asset": "node-v1.0.0-linux-arm64.tar.gz"})
+ assert M.pin_to_keep(pins, "1.0.0", asset, tmp_path) == "b" * 64
+ monkeypatch.setattr(M, "load_metadata", lambda d: None)
+ assert M.pin_to_keep(pins, "1.0.0", asset, tmp_path) == "b" * 64
+ monkeypatch.setattr(M, "load_metadata", lambda d: {"asset": "node-v1.0.0-linux-x64.tar.zst"})
+ assert M.pin_to_keep(pins, "1.0.0", asset, tmp_path) == "b" * 64
+
+
+def test_mirror_without_tar_xz_falls_back_to_pinned_tar_gz(tmp_path, monkeypatch):
+ install_dir = tmp_path / "node"
+ version = M.pinned_default_version(M.load_pins())
+ host = dataclasses.replace(_host("linux", "x64"), archive_ext = ".tar.xz")
+ monkeypatch.setattr(M, "detect_host", lambda: host)
+ monkeypatch.setattr(M, "installed_node_version", lambda d, h: version)
+ monkeypatch.setattr(M, "installed_npm_major", lambda d, h: 11)
+ monkeypatch.setattr(M, "_ensure_npm_floor", lambda d, h: None)
+ fetched = []
+
+ def fake_download(url, path, **kw):
+ fetched.append(path.name)
+ if path.name.endswith(".tar.xz"):
+ raise OSError("HTTP Error 404: Not Found")
+ path.write_bytes(b"gz")
+
+ monkeypatch.setattr(M, "download_file_verified", fake_download)
+ monkeypatch.setattr(
+ M, "extract_archive", lambda a, d: (d / "node-root" / "bin").mkdir(parents = True)
+ )
+
+ assert M.install_prebuilt(install_dir, channel = "pinned", min_major = 24, force = False) == 0
+ gz = f"node-v{version}-linux-x64.tar.gz"
+ assert fetched == [f"node-v{version}-linux-x64.tar.xz", gz]
+ meta = M.load_metadata(install_dir)
+ assert meta["asset"] == gz
+ assert meta["sha256"] == M.pinned_sha256(M.load_pins(), version, gz)
+
+
+def test_format_switched_by_another_installer_while_waiting_is_kept(tmp_path, monkeypatch):
+ install_dir = tmp_path / "node"
+ install_dir.mkdir()
+ pins = M.load_pins()
+ version = M.pinned_default_version(pins)
+ gz, xz = (f"node-v{version}-linux-x64.tar.{ext}" for ext in ("gz", "xz"))
+ M.write_metadata(install_dir, version = version, asset = gz, sha256 = "stale")
+ host = dataclasses.replace(_host("linux", "x64"), archive_ext = ".tar.xz")
+ monkeypatch.setattr(M, "detect_host", lambda: host)
+ monkeypatch.setattr(M, "installed_node_version", lambda d, h: version)
+ monkeypatch.setattr(M, "installed_npm_major", lambda d, h: 11)
+ real_lock = M.install_lock
+
+ @contextlib.contextmanager
+ def lock_after_other_installer(path):
+ M.write_metadata(
+ install_dir, version = version, asset = xz, sha256 = M.pinned_sha256(pins, version, xz)
+ )
+ with real_lock(path):
+ yield
+
+ monkeypatch.setattr(M, "install_lock", lock_after_other_installer)
+ monkeypatch.setattr(M, "download_file_verified", lambda *a, **k: pytest.fail("downloaded"))
+
+ assert M.install_prebuilt(install_dir, channel = "pinned", min_major = 24, force = False) == 0