NVM for Windows — Administrator & Developer Guide

This guide documents the architecture, configuration, operations, security model, and internals of NVM for Windows (nvm) — the Node.js version manager for Windows. It is intended for system administrators deploying NVM4W across machines, support engineers diagnosing failures, and developers who want to understand or contribute to the codebase. End-user task instructions live in the companion User Guide.

NVM for Windows is a single, self-contained Go executable. It has no runtime dependency on Node.js, no service, no database, and no background daemon of its own. Its entire job is to manage a set of on-disk Node.js installations and a single Windows symlink that selects the active one.

1. Executive Summary

Operating principle: every Node.js version lives in its own directory under NVM_HOME (e.g. C:\nvm\v22.14.0). The path NVM_SYMLINK is added to the system PATH exactly once at install time. Switching versions re-points that symlink — so the change is global, instant across all shells, and persists across reboots, without ever re-editing PATH.

2. Architecture

2.1 Component overview

                          ┌─────────────────────────────────────────┐
   User terminal  ──────▶ │  nvm.exe  (package main, src/nvm.go)     │
   (Admin shell)          │  os.Args switch-dispatch CLI             │
                          └───────────────┬─────────────────────────┘
                                          │ calls internal packages
        ┌─────────────┬──────────────┬────┴───────┬─────────────┬───────────────┐
        ▼             ▼              ▼            ▼             ▼               ▼
   nvm/web        nvm/node       nvm/arch     nvm/file     nvm/utility     nvm/upgrade
   downloads,     version        PE-header    unzip,       debug logs,     self-update,
   mirrors,       discovery,     arch detect  settings I/O cross-vol move  notifications,
   proxy, SSL     install state                                            scheduled tasks
        │             │                                                         │
        ▼             ▼                                                         ▼
   nodejs.org    %NVM_HOME%\vX.Y.Z\                                       nvm/author ──▶ author-nvm.exe
   github npm    (per-version node.exe + npm)                            (companion: notifications)
        │
        ▼
   NVM_SYMLINK ──(on system PATH)──▶ re-targeted on `nvm use`

2.2 Package inventory

2.3 Command dispatch model

There is no CLI framework (no Cobra, no flag package for subcommands). main() reads os.Args and routes on args[1] with a switch. The implication for operators and contributors: the authoritative list of commands is the switch block in src/nvm.go:main() plus the hard-coded usage text in help(). Positional arguments are interpreted as: args[1] = command, args[2] = version/detail, args[3] = architecture (32/64/arm64) when applicable.

The init() function additionally registers a custom nvm:// URL-protocol handler. When nvm.exe is launched with a nvm://launch?action=... argument (from a toast-notification button), it rewrites os.Args into the equivalent command (install, use, upgrade) before main() runs.

Note

Any argument equal to verbose (dashes stripped) anywhere on the command line enables debug logging via utility.EnableDebugLogs(). This is parsed in init(), independent of the command.

2.4 The symlink switching mechanism

This is the core design decision (chosen over the .bat-shim and PATH-rewriting approaches used by older Windows version managers):

1. At install time, NVM_SYMLINK (e.g. C:\nvm\node) is added to the system PATH.
2. nvm use X validates the target, removes the existing symlink (rmdir via elevation), and creates a new directory symlink (mklink /D) pointing at %NVM_HOME%\vX.
3. Because the symlink — not the version folders — is on PATH, the active node/npm change everywhere at once and survive reboots.

Architecture selection is handled by renaming executables inside the active version folder: node32.exe/node64.exe are swapped to/from node.exe so the on-PATH node matches the requested bitness.

3. System Requirements

Important

NVM_HOME and NVM_SYMLINK must be different paths, and NVM_SYMLINK must point at a location that does not already exist as a physical directory. The debug command enforces both invariants and warns if violated.

4. Configuration Reference

4.1 Environment variables

These are read directly from the process environment (os.Getenv). The installer sets the first two.

4.2 settings.txt

The persistent configuration file, stored at %NVM_HOME%\settings.txt. It is a plain-text, colon-delimited key/value file (one pair per line) — not YAML or JSON. It is written by saveSettings() and parsed by setup(). Values are passed through os.ExpandEnv, so environment-variable references like %APPDATA% are expanded on read.

Example (examples/settings.txt):

root: C:\Users\Corey\AppData\Roaming\nvm
path: C:\Program Files\nodejs
arch: 64
proxy: none

Caution

Do not hand-edit settings.txt to point root/symlink at a real Node.js directory. validSymlink() deliberately refuses to delete a path that is a physical file/directory rather than a symlink — an anti-footgun added after users corrupted installs by manual edits. Use the nvm commands instead.

4.3 Download endpoints and defaults

Defined in src/web/web.go:

Mirror URLs are normalized: a missing scheme gets http:// prepended, and a trailing / is enforced.

5. Operations

5.1 Installation and provisioning

Deploy via the Inno Setup installer (nvm-setup.exe) built from nvm.iss. The installer:

• Writes nvm.exe and author-nvm.exe to the install directory.
• Sets NVM_HOME and NVM_SYMLINK environment variables.
• Adds NVM_SYMLINK to the system PATH.
• Optionally absorbs an existing Node.js installation (copying its files and global modules into the NVM root, since Windows forbids cross-vendor uninstalls).

For fleet deployment, standardize NVM_HOME/NVM_SYMLINK paths and pre-remove any baseline Node.js image to avoid PATH conflicts (the #1 support issue).

5.2 Health check — nvm debug

nvm debug (checkLocalEnvironment()) is the primary operational diagnostic. It reports and validates:

• Administrator vs. elevated vs. standard rights, and Windows Developer Mode status.
• PATH conflicts — another node.exe ahead of the symlink.
• Console type (warns if not Command Prompt/PowerShell).
• Windows build number (via RtlGetNtVersionNumbers).
• NVM4W version, author-bridge version, resolved binary path, settings path.
• NVM_HOME / NVM_SYMLINK values, and that they differ and are not nested.
• Whether the symlink exists and actually is a symlink pointing at a directory.
• IPv6 status (flagged as a possible download-slowness cause).
• Reachability of the Node version index (accounting for mirror/proxy).
• Installed versions missing node.exe (invalid) or npm.cmd (Node-only).
• Presence of settings.txt.
• Availability of an NVM4W self-update.

A clean machine prints No problems detected.; otherwise a PROBLEMS DETECTED block lists each issue with a remediation hint. Use this as the first step in any support ticket.

5.3 Logs

• Fatal errors are appended to error.log next to nvm.exe (writeToErrorLog), and some upgrade/scheduling paths write error.log in the working directory.
• Verbose/debug logging is opt-in: add verbose to any command. Output is ANSI-colored (utility.DebugLogf) and includes the resolved command, architecture, download URLs, and file moves.

Tip

When collecting diagnostics for a bug report, re-run the failing command with verbose appended and attach both the console output and any error.log next to nvm.exe.

5.4 Self-update lifecycle

nvm upgrade (upgrade.Run → run) performs:

1. Query the GitHub releases API (api.github.com/repos/coreybutler/nvm-windows/releases/latest) and the alerts feed (author.io/nvm4w/feed/alerts).
2. Compare the running version against the latest; abort early if already current.
3. Download nvm-noinstall.zip plus its .checksum.txt; verify with an MD5 comparison (abort on mismatch).
4. Extract to a temp dir; download any extra assets (e.g. update.exe).
5. Zip the current install as a backup and copy it to a hidden .update\nvm4w-backup.zip.
6. Copy new files over the install directory; stage the new nvm.exe under .update\.
7. Write and launch updater.bat, which waits for the current PID to exit, swaps in the new nvm.exe, schedules a RemoveNVM4WBackup cleanup task (~7 days out), and relaunches via the nvm://launch?action=upgrade_notify protocol.

Warning

Negative knowledge — rollback is not wired up in this build. The user-facing help text advertises "Manual rollback available for 7 days after upgrade," and the backup is created and retained for 7 days. However, the rollback argument handler inside upgrade.run() is entirely commented out in this commit. To revert, reinstall the prior release from the GitHub releases page; do not rely on an nvm upgrade rollback-style command — it does not exist here.

5.5 Notifications and scheduled checks

nvm subscribe <topic> (topics: lts, current, nvm4w, author) registers Windows scheduled tasks via schtasks (src/upgrade/register.go), each running nvm checkForUpdates <topic> hourly at a staggered minute:

Notification de-duplication state lives in %APPDATA%\.nvm\.updates.json (hidden). Toast notifications and the actual notification delivery route through the external author-nvm.exe via nvm/author.Bridge. nvm unsubscribe <topic> removes the corresponding scheduled task.

5.6 Backup and recovery

• Node versions are independent directories under NVM_HOME; backing up that tree backs up all installed runtimes.
• Configuration is a single settings.txt.
• NVM4W binary backups are produced automatically on upgrade (.update\nvm4w-backup.zip, 7-day retention).
• To recover a corrupted version: nvm reinstall <version>. To recover NVM4W itself: re-run the installer for the desired release.

6. Security Analysis

Caution

Treat --insecure as a break-glass option for TLS-intercepting corporate proxies only. Because update integrity relies on MD5, do not depend on the checksum step as a tamper-evidence control on untrusted networks — verify you are pulling releases from the official GitHub project, and prefer the Authenticode-signed installer for distribution.

7. Code Quality & Patterns

• Concurrency: install, use, and upgrade run their work in goroutines coordinated by a Status channel and a sync.WaitGroup, while a foreground goroutine renders progress (either console text or a zenity progress dialog when --show-progress-ui is set). Signal handling (SIGINT/SIGTERM) triggers rollback of partial installs.
• Architecture detection is done by byte-scanning the PE header of node.exe (arch.Bit: arm64 = 5045000064AA, x64 = 504500006486, x86 = 504500004C), rather than trusting filenames.
• Cross-volume moves: utility.Rename falls back from os.Rename to a recursive copy-then-delete when source and destination are on different drives — important because temp downloads and the NVM root may live on different volumes. Large-extract races are handled with exponential backoff (1/2/4/8/16s) when moving npm into place.
• Vendored semver: the project vendors a semver package (src/semver) in addition to importing blang/semver, used in the upgrade comparison paths.
• Error surface: 92 distinct error strings were catalogued across the codebase (richest in src/semver and src/nvm.go), giving precise, user-actionable messages — these double as the canonical troubleshooting catalog.

Conventions for contributors

• Add new commands to the switch in src/nvm.go:main() and to the help() usage text — they are maintained by hand and must stay in sync.
• Positional argument slots are fixed (args[2] = version, args[3] = arch); preserve this contract.
• Keep new user-facing failures as explicit error strings with remediation guidance, consistent with the existing catalog.

8. Build & Contributing

The build is driven by src/manifest.json (name, version, build entrypoint nvm.go, output ../bin, minify, release/dev profiles) and an Inno Setup script (nvm.iss). A Deno helper, build.js, injects the manifest version into nvm.iss and invokes assets\buildtools\iscc.exe to compile the installer.

From source (per the README):

# Install Go from https://golang.org
git clone https://github.com/coreybutler/nvm-windows
cd nvm-windows\src
go get github.com/blang/semver
go get github.com/olekukonko/tablewriter
build.bat
# resulting setup program lands in the dist directory

Note

The build deliberately uses Go (and a Deno helper for the installer) rather than Node.js — the author's stated rationale is that a Node version manager should not depend on the tool it installs.

Key dependencies

9. Potential Improvements

These are observations drawn from the source as it stands at this commit.

• Wire up rollback. The 7-day backup is created and advertised in help text, but the rollback handler is commented out. Either implement the restore path or correct the help text to avoid setting a false expectation.
• Strengthen update integrity. Replace the MD5 update checksum with SHA-256, and consider verifying a signature over the payload rather than relying on the installer's Authenticode signature alone.
• Unify zip extraction. Two unzip implementations coexist (web.unzip with a full ZipSlip guard, file.Unzip with only a .. substring check). Consolidate on the hardened version.
• Formalize the command surface. The hand-maintained switch/help() pairing is easy to desynchronize. A small command-registry table (name, aliases, handler, help) would remove the duplication and make --version/alias handling uniform.
• Externalize settings.txt parsing edge cases. The colon-delimited parser splits on the first : and rejoins the remainder, which is correct for Windows paths but is custom logic worth unit-testing against values containing : and expanded env vars.
• arm64/64 availability heuristics (IsNode64bitAvailable, IsNodeArm64bitAvailable) carry TODO: fixme and optimistically assume availability above a version threshold. A definitive check against the version index would prevent misleading "only available in 32-bit" errors.

10. Quick Reference

Files and locations

Network endpoints

Operational commands

Architecture availability rules