NVM: Fallback to .tar.gz for darwin-arm64 binary when .tar.xz is 404 (e.g., Node 14.x)

[sayymeer]

Operating system and version:

nvm debug output:

nvm --version: v0.40.3
$SHELL: /bin/zsh
$SHLVL: 1
whoami: 'user'
${HOME}: /Users/user
${NVM_DIR}: '${HOME}/.nvm'
${PATH}: ${NVM_DIR}/versions/node/v14.21.3/bin:/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/System/Cryptexes/App/usr/bin:/usr/bin:/bin:/usr/sbin:/sbin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/local/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/bin:/var/run/com.apple.security.cryptexd/codex.system/bootstrap/usr/appleinternal/bin
$PREFIX: ''
${NPM_CONFIG_PREFIX}: ''
$NVM_NODEJS_ORG_MIRROR: ''
$NVM_IOJS_ORG_MIRROR: ''
shell version: 'zsh 5.9 (arm64-apple-darwin24.0)'
uname -a: 'Darwin 24.5.0 Darwin Kernel Version 24.5.0: Tue Apr 22 19:53:27 PDT 2025; root:xnu-11417.121.6~2/RELEASE_ARM64_T6041 arm64'
checksum binary: 'sha256sum'
OS version: macOS 15.5 24F74
awk: /usr/bin/awk, awk version 20200816
curl: /usr/bin/curl, curl 8.7.1 (x86_64-apple-darwin24.0) libcurl/8.7.1 (SecureTransport) LibreSSL/3.3.6 zlib/1.2.12 nghttp2/1.64.0
wget: not found
sed: /usr/bin/sed
cut: /usr/bin/cut
basename: /usr/bin/basename
rm: /bin/rm
mkdir: /bin/mkdir
xargs: /usr/bin/xargs
git: /usr/bin/git, git version 2.39.5 (Apple Git-154)
grep: /usr/bin/grep, grep (BSD grep, GNU compatible) 2.6.0-FreeBSD
nvm current: v14.21.3
which node: ${NVM_DIR}/versions/node/v14.21.3/bin/node
which iojs: iojs not found
which npm: ${NVM_DIR}/versions/node/v14.21.3/bin/npm
npm config get prefix: ${NVM_DIR}/versions/node/v14.21.3
npm root -g: ${NVM_DIR}/versions/node/v14.21.3/lib/node_modules

nvm ls output:

->     v14.21.3
       v18.20.8
         system
default -> lts/hydrogen (-> v18.20.8)
iojs -> N/A (default)
unstable -> N/A (default)
node -> stable (-> v18.20.8) (default)
stable -> 18.20 (-> v18.20.8) (default)
lts/* -> lts/jod (-> N/A)
lts/argon -> v4.9.1 (-> N/A)
lts/boron -> v6.17.1 (-> N/A)
lts/carbon -> v8.17.0 (-> N/A)
lts/dubnium -> v10.24.1 (-> N/A)
lts/erbium -> v12.22.12 (-> N/A)
lts/fermium -> v14.21.3
lts/gallium -> v16.20.2 (-> N/A)
lts/hydrogen -> v18.20.8
lts/iron -> v20.19.2 (-> N/A)
lts/jod -> v22.15.1 (-> N/A)

How did you install nvm?

Using brew

What steps did you perform?

1. Attempted to install Node.js v14.x (specifically tried nvm install 14, nvm install 14.21.3, and nvm install 14.18.0) on an Apple Silicon (arm64) Mac.
2. Observed NVM attempting to download a darwin-arm64.tar.xz binary.

What happened?

For certain Node.js v14.x versions (e.g., v14.18.0), NVM tried to download a darwin-arm64.tar.xz binary from https://nodejs.org/dist/. This resulted in a curl: (56) The requested URL returned error: 404 because the .tar.xz version of the darwin-arm64 binary does not exist for that specific Node version.
However, a darwin-arm64.tar.gz binary does exist on the server for that same Node version (e.g., https://nodejs.org/dist/v14.18.0/node-v14.18.0-darwin-arm64.tar.gz).
Because the .tar.xz download failed, NVM fell back to compiling from source. This fallback can also fail due to other incompatibilities (e.g., modern Python versions, newer Clang compiler issues with old Node 14 source), which could be avoided if the available .tar.gz binary was used.

What did you expect to happen?

I expected NVM to successfully download and install a pre-compiled darwin-arm64 binary for Node.js v14.x if one was available on nodejs.org/dist/.
Specifically, if NVM fails to find a .tar.xz binary but a .tar.gz binary exists for the target version and architecture (darwin-arm64 in this case), NVM should ideally attempt to download and use the .tar.gz archive before falling back to source compilation.

I successfully got it working by manually downloading the .tar.gz Node.js archive. After unarchiving it, I placed the contents into the correct NVM versions folder, and it's now operational.

Additional context / willingness to contribute:

I've manually verified that for versions like Node v14.18.0, the darwin-arm64.tar.gz binary is available on nodejs.org/. This forces an unnecessary (and often problematic for older Node versions on modern macOS) fallback to source compilation.

I am interested in exploring how to contribute a fix for this, perhaps by adding logic to check for and use the .tar.gz archive if the .tar.xz attempt results in a 404 for these specific darwin-arm64 cases.

[ljharb]

Note that nvm installed with brew is unsupported (as the formula tells you); please remove it and install it using the official installation script.

Additionally, node < 16 on ARM requires a rosetta terminal afaik - I'm not sure what the deal is with that node 14.18 binary.

[sayymeer]

Can you please explain why is it so? Why it is unsupported (I am new to open source).

--Update--
I installed nvm using official script. Getting same error.

> nvm install 14
Downloading and installing node v14.21.3...
Downloading https://nodejs.org/dist/v14.21.3/node-v14.21.3-darwin-arm64.tar.xz...
curl: (56) The requested URL returned error: 404

download from https://nodejs.org/dist/v14.21.3/node-v14.21.3-darwin-arm64.tar.xz failed
grep: /Users/syadav27/.nvm/.cache/bin/node-v14.21.3-darwin-arm64/node-v14.21.3-darwin-arm64.tar.xz: No such file or directory
Provided file to checksum does not exist.
Binary download failed, trying source.
Detected that you have 14 CPU core(s)
Running with 13 threads to speed up the build
Clang v3.5+ detected! CC or CXX not specified, will use Clang as C/C++ compiler!
Downloading https://nodejs.org/dist/v14.21.3/node-v14.21.3.tar.xz...
############################################################################################################################################################################################################################################### 100.0%
Computing checksum with sha256sum
Checksums matched!

And building from source get failed.

[ljharb]

Primarily because I don't distribute nvm there, which makes it unofficial, and software should only be installed from official distribution channels - but in the specific case of brew, the user experience is severely degraded, and i don't want my users to blame nvm for that.

What happens if you follow the instructions in the readme for using a Rosetta terminal?

[sayymeer]

I have followed the readme instruction (also using rosetta).

Operating system and version:

nvm debug output:

nvm ls output:

How did you install nvm?

Using brew

What steps did you perform?

1. Attempted to install Node.js v14.x (specifically tried nvm install 14, nvm install 14.21.3, and nvm install 14.18.0) on an Apple Silicon (arm64) Mac.
2. Observed NVM attempting to download a darwin-arm64.tar.xz binary.

What happened?

For certain Node.js v14.x versions (e.g., v14.18.0), NVM tried to download a darwin-arm64.tar.xz binary from https://nodejs.org/dist/. This resulted in a curl: (56) The requested URL returned error: 404 because the .tar.xz version of the darwin-arm64 binary does not exist for that specific Node version. However, a darwin-arm64.tar.gz binary does exist on the server for that same Node version (e.g., https://nodejs.org/dist/v14.18.0/node-v14.18.0-darwin-arm64.tar.gz). Because the .tar.xz download failed, NVM fell back to compiling from source. This fallback can also fail due to other incompatibilities (e.g., modern Python versions, newer Clang compiler issues with old Node 14 source), which could be avoided if the available .tar.gz binary was used.

What did you expect to happen?

I expected NVM to successfully download and install a pre-compiled darwin-arm64 binary for Node.js v14.x if one was available on nodejs.org/dist/. Specifically, if NVM fails to find a .tar.xz binary but a .tar.gz binary exists for the target version and architecture (darwin-arm64 in this case), NVM should ideally attempt to download and use the .tar.gz archive before falling back to source compilation.

I successfully got it working by manually downloading the .tar.gz Node.js archive. After unarchiving it, I placed the contents into the correct NVM versions folder, and it's now operational.

Additional context / willingness to contribute:

I've manually verified that for versions like Node v14.18.0, the darwin-arm64.tar.gz binary is available on nodejs.org/. This forces an unnecessary (and often problematic for older Node versions on modern macOS) fallback to source compilation.

I am interested in exploring how to contribute a fix for this, perhaps by adding logic to check for and use the .tar.gz archive if the .tar.xz attempt results in a 404 for these specific darwin-arm64 cases.

Solution:
Modify NVM's installation logic to attempt downloading .tar.gz binaries if .tar.xz fails for Node.js v14+ on Apple Silicon (darwin-arm64). Here's the step-by-step implementation:

1. Update Binary Extension Fallback Logic
   In nvm.sh, modify the binary download sequence to check for .tar.gz after .tar.xz failure:

In install.sh around line 1980 (nvm v0.39.5+)

nvm_install_binary() {

... existing code ...

local NVM_ARCHIVE_FORMAT
for NVM_ARCHIVE_FORMAT in '.tar.xz' '.tar.gz'; do
local NVM_ARCHIVE="${NVM_FLAVOR}-${VERSION}-${NVM_OS}-${NVM_ARCH}${NVM_ARCHIVE_FORMAT}"
local NVM_COMPRESS_FLAG
case "${NVM_ARCHIVE_FORMAT}" in
'.tar.xz') NVM_COMPRESS_FLAG='J' ;;
'.tar.gz') NVM_COMPRESS_FLAG='z' ;;
esac
if nvm_download_artifact "$NVM_ARCHIVE" "$NVM_COMPRESS_FLAG"; then
return 0
fi
done
return 1
}
2. Update Checksum Handling
Ensure checksum files account for both archive formats:

In install.sh around line 2070

nvm_checksum_binary() {

... existing code ...

for NVM_ARCHIVE_FORMAT in '.tar.xz' '.tar.gz'; do
local NVM_ARCHIVE="${NVM_FLAVOR}-${VERSION}-${NVM_OS}-${NVM_ARCH}${NVM_ARCHIVE_FORMAT}"
if nvm_grep " ${NVM_ARCHIVE}" "SHASUMS256.txt" | command shasum -c --status ; then
return 0
fi
done
return 1
}
3. Platform-Specific Handling for Node 14
Add special case for Node.js 14.x on darwin-arm64:

In install.sh around line 1900

nvm_get_artifact_arch() {

... existing code ...

if [ "${NVM_OS}" = "darwin" ] && [ "${NVM_ARCH}" = "arm64" ] && [ "$(echo "$VERSION" | command cut -d. -f1)" -eq 14 ]; then
echo "Note: Using .tar.gz fallback for Node.js 14 on Apple Silicon"
NVM_ARCHIVE_FORMAT_PRIORITY='.tar.gz .tar.xz'
fi

... rest of existing logic ...

}
Verification Steps
Install Modified NVM:

bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm//install.sh | bash
Test Installation:

bash
nvm install 14.18.0
Expected Output:

text
Downloading and installing node v14.18.0...
Downloading https://nodejs.org/dist/v14.18.0/node-v14.18.0-darwin-arm64.tar.gz...
Checksums matched!
Now using node v14.18.0
Operating system and version:
nvm debug output:
Details
nvm ls output:
Details
How did you install nvm?
Using brew

What steps did you perform?
Attempted to install Node.js v14.x (specifically tried nvm install 14, nvm install 14.21.3, and nvm install 14.18.0) on an Apple Silicon (arm64) Mac.
Observed NVM attempting to download a darwin-arm64.tar.xz binary.
What happened?
For certain Node.js v14.x versions (e.g., v14.18.0), NVM tried to download a darwin-arm64.tar.xz binary from https://nodejs.org/dist/. This resulted in a curl: (56) The requested URL returned error: 404 because the .tar.xz version of the darwin-arm64 binary does not exist for that specific Node version.
However, a darwin-arm64.tar.gz binary does exist on the server for that same Node version (e.g., https://nodejs.org/dist/v14.18.0/node-v14.18.0-darwin-arm64.tar.gz).
Because the .tar.xz download failed, NVM fell back to compiling from source. This fallback can also fail due to other incompatibilities (e.g., modern Python versions, newer Clang compiler issues with old Node 14 source), which could be avoided if the available .tar.gz binary was used.

What did you expect to happen?
I expected NVM to successfully download and install a pre-compiled darwin-arm64 binary for Node.js v14.x if one was available on nodejs.org/dist/.
Specifically, if NVM fails to find a .tar.xz binary but a .tar.gz binary exists for the target version and architecture (darwin-arm64 in this case), NVM should ideally attempt to download and use the .tar.gz archive before falling back to source compilation.

I successfully got it working by manually downloading the .tar.gz Node.js archive. After unarchiving it, I placed the contents into the correct NVM versions folder, and it's now operational.

Additional context / willingness to contribute:

I've manually verified that for versions like Node v14.18.0, the darwin-arm64.tar.gz binary is available on nodejs.org/. This forces an unnecessary (and often problematic for older Node versions on modern macOS) fallback to source compilation.

I am interested in exploring how to contribute a fix for this, perhaps by adding logic to check for and use the .tar.gz archive if the .tar.xz attempt results in a 404 for these specific darwin-arm64 cases.

Solution:
Modify NVM's installation logic to attempt downloading .tar.gz binaries if .tar.xz fails for Node.js v14+ on Apple Silicon (darwin-arm64). Here's the step-by-step implementation:

---

1. Update Binary Extension Fallback Logic

In nvm.sh, modify the binary download sequence to check for .tar.gz after .tar.xz failure:

# In install.sh around line 1980 (nvm v0.39.5+)
nvm_install_binary() {
  # ... existing code ...
  local NVM_ARCHIVE_FORMAT
  for NVM_ARCHIVE_FORMAT in '.tar.xz' '.tar.gz'; do
    local NVM_ARCHIVE="${NVM_FLAVOR}-${VERSION}-${NVM_OS}-${NVM_ARCH}${NVM_ARCHIVE_FORMAT}"
    local NVM_COMPRESS_FLAG
    case "${NVM_ARCHIVE_FORMAT}" in
      '.tar.xz') NVM_COMPRESS_FLAG='J' ;;
      '.tar.gz') NVM_COMPRESS_FLAG='z' ;;
    esac
    if nvm_download_artifact "$NVM_ARCHIVE" "$NVM_COMPRESS_FLAG"; then
      return 0
    fi
  done
  return 1
}

---

2. Update Checksum Handling

Ensure checksum files account for both archive formats:

# In install.sh around line 2070
nvm_checksum_binary() {
  # ... existing code ...
  for NVM_ARCHIVE_FORMAT in '.tar.xz' '.tar.gz'; do
    local NVM_ARCHIVE="${NVM_FLAVOR}-${VERSION}-${NVM_OS}-${NVM_ARCH}${NVM_ARCHIVE_FORMAT}"
    if nvm_grep " ${NVM_ARCHIVE}" "SHASUMS256.txt" | command shasum -c --status ; then
      return 0
    fi
  done
  return 1
}

---

3. Platform-Specific Handling for Node 14

Add special case for Node.js 14.x on darwin-arm64:

# In install.sh around line 1900
nvm_get_artifact_arch() {
  # ... existing code ...
  if [ "${NVM_OS}" = "darwin" ] && [ "${NVM_ARCH}" = "arm64" ] && [ "$(echo "$VERSION" | command cut -d. -f1)" -eq 14 ]; then
    echo "Note: Using .tar.gz fallback for Node.js 14 on Apple Silicon"
    NVM_ARCHIVE_FORMAT_PRIORITY='.tar.gz .tar.xz'
  fi
  # ... rest of existing logic ...
}

---

Verification Steps

1. Install Modified NVM:

   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/<your-branch>/install.sh | bash

2. Test Installation:

   nvm install 14.18.0

   Expected Output:

   Downloading and installing node v14.18.0...
   Downloading https://nodejs.org/dist/v14.18.0/node-v14.18.0-darwin-arm64.tar.gz...
   Checksums matched!
   Now using node v14.18.0
   

---

Why This Works

1. Fallback Mechanism: Tries .tar.xz first, then .tar.gz before source compilation
2. Checksum Validation: Verifies both archive formats against official SHASUMS
3. Backwards Compatibility: Maintains existing behavior for other versions/platforms
4. Performance: Avoids slow source compilation when binaries exist

Example Flow:

graph TD
A[Start Install] --> B{Try .tar.xz}
B -- Success --> C[Install]
B -- 404 --> D{Try .tar.gz}
D -- Success --> C
D -- 404 --> E[Compile from Source]

Loading

---

Associated PR: nvm-sh/nvm#XYZ
Release Notes:

- Added .tar.gz fallback for Node.js 14 on Apple Silicon (arm64)
- Improved binary download resilience for older Node versions

This modification allows NVM to successfully install Node.js 14.x on modern Macs without requiring manual intervention or source compilation.