# How nvm Handles Binary vs Source Installation: When to Use Each Method

> Discover how nvm handles binary vs source installation. Learn when to use each method for efficient Node.js management and avoid compilation issues.

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

---

**nvm always attempts to download pre-compiled binaries first and automatically falls back to compiling from source only when binaries are unavailable, extraction fails, or the user explicitly disables binary downloads.**

The `nvm-sh/nvm` repository implements a dual-path installation system that prioritizes speed and convenience while ensuring compatibility across unsupported platforms. Understanding how `nvm` chooses between these methods helps you optimize installation times and troubleshoot failures on exotic architectures or older Node.js versions.

## The Binary Installation Path

### Entry Point and URL Construction

In [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh) (lines 2299-2630), the `nvm_install_binary()` function orchestrates the default installation flow. The process begins by detecting your operating system via `nvm_get_os` and constructing a platform-specific download slug through `nvm_download_artifact` (lines 445-470).

This generates a URL pattern like `node-14.21.3-linux-x64.tar.gz` based on your architecture and OS, then fetches the artifact from the configured Node.js mirror with a progress indicator.

### Extraction and File Placement

Once downloaded, `nvm_install_binary_extract()` (lines 2250-2289) handles decompression and placement:

- Creates a temporary directory for safe extraction
- On Windows environments, uses `unzip` directly
- On Unix-like systems, delegates to `nvm_extract_tarball`
- Moves extracted binaries into `$NVM_DIR/versions/node/[version]/`

If extraction succeeds (returns `0`), `nvm` immediately creates any user-requested aliases and completes the installation without compiling anything.

### Automatic Fallback Logic

When `nvm_install_binary_extract` returns a non-zero exit code, `nvm` evaluates the failure context (lines 62-70 in [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh)). If you invoked the install with a `nosource` flag, the process aborts with the error *"Binary download failed. Download from source aborted."* Otherwise, it prints *"Binary download failed, trying source"* and automatically invokes `nvm_install_source`.

## The Source Installation Path

### Build Environment Preparation

The `nvm_install_source()` function (lines 2634-3041) activates when binaries are unavailable or explicitly disabled. It first detects your CPU architecture via `nvm_get_arch` and applies platform-specific optimizations. For ARM chips, it automatically appends `--without-snapshot` to configure flags (lines 65-71) to avoid V8 snapshot generation issues on limited memory devices.

### Compiler Selection and Configuration

Before compilation, `nvm` inspects your toolchain (lines 90-106 in [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh)):

- **Make selection**: Chooses between `make` and `gmake` based on OS detection
- **Compiler preference**: If Clang ≥ 3.5 is available, it sets `CC` and `CXX` to `clang` and `clang++` for faster builds and better error messages
- **Parallelization**: Respects the `NVM_MAKE_JOBS` environment variable for multi-core compilation

### Download, Configure, and Compile

The source workflow mirrors the binary path initially by downloading a source tarball via `nvm_download_artifact ... source` (lines 22-26). After extraction into a temporary folder, the build sequence executes:

1. `./configure --prefix=$VERSION_PATH` with any additional user-provided flags
2. `$make -j $NVM_MAKE_JOBS` to compile the Node.js binary
3. `make install` to place files in the version directory

If any step fails, `nvm` removes the temporary directory and emits a clear error message (lines 36-40), leaving your system clean without partial installations.

## When to Use Binary vs Source Installation

**Binary installation** is the optimal choice for standard Linux x64, macOS, and Windows Git-Bash environments. Pre-compiled binaries require no local toolchain, install in seconds, and include verified cryptographic checksums.

**Source installation** becomes necessary in these specific scenarios:

- **Unsupported platforms**: Older ARM variants (armv6l), exotic BSD systems, or niche architectures where Node.js Foundation never shipped pre-built binaries
- **Missing historical binaries**: Very old Node.js versions (e.g., 0.10.48) that predated ARM binary support
- **Custom compile-time flags**: When you need `--without-snapshot`, `--openssl-legacy-provider`, or other configure options that binary downloads ignore
- **Strict reproducibility requirements**: Building from source lets you audit exact compilation flags, linked libraries, and apply security patches

**Binary-only restrictions** apply to environments lacking a C/C++ toolchain. If your system has no `make`, `gcc`, or `clang`, source compilation will fail immediately, forcing you to rely on available binaries or install build dependencies first.

## Controlling Installation Behavior

While `nvm` automatically selects the appropriate method, you can override this behavior using flags and environment variables:

```bash

# Install latest LTS using binary (default behavior)

nvm install --lts

# Force compilation from source with custom options

nvm install 16.20.0 --source

# Install old version on ARM where no binary exists - automatic fallback

nvm install 0.10.48

# Disable binary downloads entirely (fail if no source can be built)

export NVM_NO_BINARY=1
nvm install 14.17.0

```

The `--source` flag bypasses the binary check entirely, while `NVM_NO_BINARY=1` inverts the logic to skip binary attempts. Use the former for custom builds and the latter only when you need strict source verification.

## Summary

- **Binary-first architecture**: `nvm_install_binary()` in [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh) attempts downloads before any compilation occurs, maximizing speed for supported platforms.
- **Automatic resilience**: Failed binary extractions trigger `nvm_install_source()` without user intervention, ensuring installations succeed on unsupported hardware.
- **Toolchain requirements**: Source builds require `make`, `gcc`/`clang`, and Python, while binary installs need only `curl`/`wget` and standard Unix utilities.
- **Explicit control**: Use `--source` to force compilation or `NVM_NO_BINARY=1` to require source builds for security auditing.
- **Platform optimization**: ARM builds automatically receive `--without-snapshot` flags, and Clang ≥ 3.5 is preferred over GCC when available.

## Frequently Asked Questions

### Does nvm install from source or binary by default?

**Binary installation is the default.** According to the [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh) implementation (lines 2299-2630), every `nvm install` command first attempts `nvm_install_binary()`. Only if the download fails or you pass the `--source` flag does it execute `nvm_install_source()` (lines 2634-3041).

### How do I force nvm to compile Node.js from source?

**Pass the `--source` flag** to your install command: `nvm install 18.17.0 --source`. This bypasses `nvm_install_binary()` entirely and immediately invokes the compilation workflow with `./configure` and `make`. You can also set `export NVM_NO_BINARY=1` in your shell profile to default all future installs to source builds.

### Why does nvm fail with "Binary download failed" on my ARM device?

**Pre-compiled binaries for ARM are limited to recent Node.js versions and specific architectures.** For older 32-bit ARM (armv6l) or Node.js versions prior to 4.x, the Node.js Foundation never shipped binaries. `nvm` automatically falls back to source compilation in these cases, but you must have `make`, `gcc`, and Python installed. The error clears once you install the build toolchain or request a newer Node.js version with ARM support.

### Can I use nvm on systems without a C++ compiler?

**Yes, but only for platforms with available binaries.** If you are on x64 Linux, macOS, or Windows Git-Bash, `nvm` downloads pre-compiled binaries without requiring `gcc` or `clang`. However, if you attempt to install an unsupported version or use `NVM_NO_BINARY=1`, the installation will fail because `nvm_install_source()` cannot compile without a C++ toolchain.