NVM (Node Version Manager) — Core Functionality#

Overview#

NVM is a POSIX-compliant shell function (not a binary) for managing multiple active Node.js versions per user, per shell. It supports sh, dash, bash, ksh, and zsh 1. The entire implementation lives in a single sourced file — no compiled code involved.

Key files:

Shell Startup Initialization#

Profile snippet#

The installer adds the following to ~/.bashrc, ~/.bash_profile, ~/.zshrc, or ~/.profile 2:

export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm

Pass --no-use as an argument to suppress automatic version activation 3. If $XDG_CONFIG_HOME is set, nvm files are placed there instead of ~/.nvm 4.

Auto-mode: nvm_process_parameters → nvm_auto#

At the very end of nvm.sh, nvm_process_parameters "$@" runs unconditionally on every source 5. It parses the startup flags and calls nvm_auto with one of three modes:

NVM_DIR is auto-detected at startup by using nvm_cd ${NVM_CD_FLAGS} to resolve the script's own directory 6 — NVM_CD_FLAGS is set for zsh compatibility (see below).

.nvmrc File Parsing#

Discovery#

nvm_find_nvmrc delegates to nvm_find_up '.nvmrc', which walks up $PWD one directory at a time until it finds the file or reaches the root 7. This means any subdirectory of a project with .nvmrc will inherit it 8.

File format#

.nvmrc must contain exactly one nvm-recognized version string (e.g., 5.9, lts/*, node) followed by a newline 9. Format rules 10:

• # starts a comment; everything after it on a line is ignored.
• Blank lines and leading/trailing whitespace are ignored.
• key=value pairs are allowed (silently skipped; reserved for future use).
• Multiple bare version strings are invalid.

Run npx nvmrc to validate a .nvmrc file 11.

Parsing: nvm_process_nvmrc_content#

nvm_process_nvmrc_content performs these steps:

1. sed 's/#.*//' strips comments; another sed pass trims whitespace; blank lines are filtered out 12.
2. Each remaining line is classified: bare version string vs. key=value pair. Duplicate keys, multiple bare strings, or lines starting with = (missing key) cause validation failure 13.
3. On success, the single bare version string is echoed to stdout. On failure, nvm_nvmrc_invalid_msg prints a diagnostic and returns 1.

nvm_rc_version is the public entry point: it orchestrates discovery → parsing and writes the resolved version to fd 3. Callers (e.g., nvm use) capture it with the idiom { version="$(nvm_rc_version 3>&1 1>&4)"; } 4>&1.

zsh extendedglob Compatibility#

NVM uses several techniques to prevent zsh's stricter glob handling from causing failures.

NVM_CD_FLAGS=-q#

On startup, when zsh is detected via nvm_is_zsh, NVM_CD_FLAGS is set to -q 14. The -q flag quiets zsh's "no matches found" error that arises from extendedglob/nomatch when a glob pattern in a cd path goes unmatched. The nvm_cd wrapper always passes $NVM_CD_FLAGS to \cd.

setopt local_options guards#

Changes to zsh shell options are scoped with nvm_is_zsh && setopt local_options … so they don't leak out of the calling function. Key sites:

ERR_RETURN in subshells#

nvm_has_executable runs in a subshell and uses || true on unalias and unset -f calls specifically because zsh's ERR_RETURN option would abort the subshell on a non-zero exit from those builtins.

Source builds on old Node (< 0.12)#

When compiling Node from source for versions before 0.12, SHELL=/bin/sh is injected into the make invocation to prevent zsh's strict glob handling from interfering with unquoted glob patterns in Node's Makefiles 15.

Key Environment Variables#

Call Chain: nvm use (no version argument)#

nvm use
  → nvm_rc_version # (cite:github_file:b0c49709:631-653)
      → nvm_find_nvmrc # walks up $PWD for .nvmrc
        → nvm_find_up '.nvmrc' # (cite:github_file:b0c49709:521-533)
      → nvm_process_nvmrc # reads file content
        → nvm_process_nvmrc_content # strips comments, validates, returns version
  → nvm_version "${provided_version}"
  → nvm_change_path / export PATH

The same .nvmrc lookup (nvm_rc_version) is used by nvm install, nvm which, nvm run, nvm exec, and nvm_auto during shell startup.

Deeper shell integration: For automatic per-directory switching (e.g., nvm use on every cd), see the bash and zsh hook recipes in README.md.