# How nvm Computes and Verifies Checksums for Downloaded Node.js Binaries

> Learn how nvm computes and verifies checksums for Node.js binaries by calculating SHA-256 hashes and comparing them to official release values. Ensure your downloads are authentic.

- Repository: [nvm.sh/nvm](https://github.com/nvm-sh/nvm)
- Tags: internals
- Published: 2026-02-27

---

**nvm computes and verifies checksums by detecting available system hashing tools, calculating the SHA-256 hash of downloaded binaries, and comparing it against official values from the Node.js release index.**

When you run `nvm install`, the tool downloads pre-compiled Node.js binaries from the official registry. To ensure these files arrive uncorrupted and unmodified, nvm implements a robust checksum verification pipeline inside [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh). This process safeguards against network errors, incomplete downloads, and supply-chain attacks by validating every byte against cryptographic hashes published by the Node.js project.

## The Five-Stage Checksum Verification Pipeline

The verification logic in [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh) operates through a sequence of specialized functions, each handling a distinct phase of the validation process.

### Stage 1: Detecting the Checksum Binary (`nvm_get_checksum_binary`)

Before computing any hash, nvm must identify which checksum utility is available on the host system. The function `nvm_get_checksum_binary` scans the `$PATH` for a prioritized list of tools:

- `sha256sum` (GNU coreutils)
- `shasum` (macOS default, with `-a 256` flag)
- `sha256` (BSD-style)
- `gsha256sum` (Homebrew GNU coreutils on macOS)
- `openssl dgst -sha256`
- `bssl sha256sum`
- Legacy `sha1sum` or `shasum -a 1` for older Node.js versions

The function returns the first detected binary, enabling nvm to work across Linux, macOS, and BSD systems without hard dependencies.

### Stage 2: Selecting the Algorithm (`nvm_get_checksum_alg`)

Node.js releases currently publish **SHA-256** checksums. The `nvm_get_checksum_alg` function normalizes the algorithm identifier from the remote index, ensuring the string is formatted as "sha-256" for internal consistency. This abstraction allows nvm to adapt if the Node.js project ever migrates to SHA-512 or other algorithms.

### Stage 3: Computing the File Hash (`nvm_compute_checksum`)

Once the tool and algorithm are identified, `nvm_compute_checksum` executes the detected binary against the downloaded file. The function constructs the appropriate command-line invocation based on the tool detected in Stage 1:

```bash

# Example invocations generated by nvm_compute_checksum

sha256sum /path/to/node-v20.0.0-linux-x64.tar.xz
shasum -a 256 /path/to/node-v20.0.0-linux-x64.tar.xz
openssl dgst -sha256 /path/to/node-v20.0.0-linux-x64.tar.xz

```

The function extracts the hash value from the command output, handling variations in formatting between different tools, and returns the clean hexadecimal string.

### Stage 4: Retrieving the Expected Checksum (`nvm_get_checksum`)

Before comparison, nvm must fetch the official checksum from the Node.js release infrastructure. The `nvm_get_checksum` function constructs the URL to the [`SHASUMS256.txt`](https://github.com/nvm-sh/nvm/blob/main/SHASUMS256.txt) file (or platform-specific variants like `SHASUMS256.txt.asc` for signed versions) based on:

- The Node.js version (e.g., `v20.0.0`)
- The platform identifier (e.g., `linux-x64`)
- The compression format (e.g., `tar.xz`)

It downloads this file, parses the contents to locate the line matching the specific binary filename, and extracts the expected SHA-256 hash.

### Stage 5: Comparing and Validating (`nvm_compare_checksum`)

The final verification occurs in `nvm_compare_checksum`. This function receives the path to the downloaded tarball and the expected checksum string retrieved in Stage 4. It calls `nvm_compute_checksum` to generate the actual hash, then performs a case-insensitive string comparison.

If the values match, the function returns success (exit code 0), and nvm proceeds with extraction. If they differ, nvm aborts the installation with an error message indicating a checksum mismatch, protecting the user from corrupted or tampered files.

## Supported Checksum Tools and Fallback Behavior

nvm is designed to function across diverse Unix-like environments. The `nvm_get_checksum_binary` function implements a comprehensive fallback chain:

1. **GNU coreutils**: `sha256sum` (Linux standard)
2. **macOS/BSD**: `shasum -a 256` (Perl-based utility)
3. **Homebrew GNU**: `gsha256sum` (prefixed GNU tools on macOS)
4. **OpenSSL**: `openssl dgst -sha256` (universal fallback)
5. **BoringSSL**: `bssl sha256sum` (Google's SSL library)
6. **Legacy SHA-1**: `sha1sum` or `shasum -a 1` for older Node.js releases

If no checksum tool is detected, `nvm_compare_checksum` emits a warning via `nvm_err` stating "Provided checksum to compare to is empty," and depending on the context, may allow the installation to proceed with a visible warning or abort with an error.

## Practical Examples

### Manually Computing a Checksum for a Downloaded Tarball

You can leverage nvm's internal functions to compute checksums for any file, not just Node.js binaries:

```bash

# Load nvm functions into current shell

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# Path to your downloaded file

FILE="/tmp/node-v20.0.0-linux-x64.tar.xz"

# Compute the checksum using nvm's detection logic

CHECKSUM=$(nvm_compute_checksum "$FILE")
echo "SHA-256: $CHECKSUM"

```

This uses `nvm_compute_checksum` from [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh) to automatically select the appropriate system tool and return the hash.

### Verifying a Download in a Custom Script

If you are building automation that downloads Node.js independently of `nvm install`, you can still use nvm's verification functions:

```bash
#!/usr/bin/env bash
set -e

# Initialize nvm

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

VERSION="v20.0.0"
PLATFORM="linux-x64"
COMPRESSION="tar.xz"
TARBALL="node-${VERSION}-${PLATFORM}.${COMPRESSION}"

# Download binary (example using curl)

curl -fsSL "https://nodejs.org/dist/${VERSION}/${TARBALL}" -o "/tmp/${TARBALL}"

# Fetch expected checksum from official index

EXPECTED=$(nvm_get_checksum "node" "linux" "$VERSION" "$PLATFORM" "$COMPRESSION")

# Verify

if nvm_compare_checksum "/tmp/${TARBALL}" "$EXPECTED"; then
  echo "✅ Checksum verification passed"
  tar -xf "/tmp/${TARBALL}" -C /usr/local --strip-components=1
else
  echo "❌ Checksum mismatch - possible corruption or tampering"
  exit 1
fi

```

This script demonstrates the complete verification pipeline: `nvm_get_checksum` retrieves the official hash, and `nvm_compare_checksum` validates the local file against it.

## Summary

- **nvm computes and verifies checksums** through a five-stage pipeline implemented entirely in [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh).
- **Tool detection** (`nvm_get_checksum_binary`) supports `sha256sum`, `shasum`, `openssl`, and legacy fallbacks across Linux, macOS, and BSD systems.
- **Algorithm selection** (`nvm_get_checksum_alg`) currently enforces SHA-256 for all modern Node.js releases.
- **Verification** (`nvm_compare_checksum`) performs string comparison between computed and expected hashes, aborting installation on mismatch or warning when tools are unavailable.
- **Official checksums** are fetched from Node.js release infrastructure via `nvm_get_checksum`, which parses [`SHASUMS256.txt`](https://github.com/nvm-sh/nvm/blob/main/SHASUMS256.txt) files.

## Frequently Asked Questions

### What checksum algorithm does nvm use?

nvm uses **SHA-256** for all modern Node.js versions. The `nvm_get_checksum_alg` function in [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh) normalizes the algorithm identifier to "sha-256" based on the official Node.js release index, which publishes SHA-256 checksums in [`SHASUMS256.txt`](https://github.com/nvm-sh/nvm/blob/main/SHASUMS256.txt) files.

### What happens if nvm cannot find a checksum tool on my system?

If `nvm_get_checksum_binary` fails to locate `sha256sum`, `shasum`, `openssl`, or any supported alternative, `nvm_compare_checksum` emits a warning via `nvm_err` stating that the checksum cannot be computed. Depending on the context, nvm may either abort the installation with an error or proceed with a visible warning that the binary could not be verified.

### Can I skip checksum verification when installing Node.js with nvm?

While nvm does not expose a direct command-line flag to disable checksum verification, the verification can effectively be skipped if no checksum tool is present on the system, in which case nvm warns the user and may continue. However, when checksum tools are available, nvm enforces verification and aborts on mismatch to prevent installation of corrupted or tampered binaries.

### Where does nvm download the official checksums from?

nvm downloads checksums from the official Node.js distribution infrastructure. The `nvm_get_checksum` function constructs URLs pointing to [`SHASUMS256.txt`](https://github.com/nvm-sh/nvm/blob/main/SHASUMS256.txt) (or platform-specific variants) hosted at `https://nodejs.org/dist/${VERSION}/`. It parses these files to extract the specific hash matching the binary filename, platform, and compression format being installed.