nvm Environment Variables: Complete Reference for Configuration and Internal Usage

nvm exposes 15+ environment variables that control installation paths, download mirrors, color output, debugging, and LTS filtering, all read at startup in nvm.sh and consumed by internal functions like nvm_get_mirror and nvm_change_path.

The nvm-sh/nvm repository implements Node Version Manager as a pure-shell script that drives all behavior through nvm environment variables. These variables are read once when nvm.sh is sourced and then consulted by internal helper functions for version resolution, download mirroring, path manipulation, and user-visible output.

Core Directory and Navigation Configuration

NVM_DIR

NVM_DIR defines the root directory where nvm stores versions/, alias/, and other metadata. All other paths are built relative to this location.

In nvm.sh, the variable is auto-detected from the script location and exported at lines 447–460:

export NVM_DIR="${NVM_DIR:-"$(cd -- "$(dirname -- "$0")" && pwd)"}"}

Every internal function references $NVM_DIR to locate installed versions and alias files.

NVM_CD_FLAGS

NVM_CD_FLAGS specifies flags passed to the cd command when nvm changes directories internally. This is declared early in nvm.sh at lines 440–443 and exported to ensure consistent navigation behavior across helper functions.

Version Resolution and Installation Control

NVM_RC_VERSION

NVM_RC_VERSION holds the version string read from a .nvmrc file (or NVM_ENV_VERSION). It is exported with a default empty value at lines 605–607 and consumed by the nvm auto functionality to determine which Node version to activate when entering a directory.

NVM_LTS

NVM_LTS controls LTS-only filtering for commands like nvm install --lts or nvm ls-remote --lts. It accepts * (any LTS) or a specific LTS name (e.g., hydrogen).

According to the source code, this variable is propagated through remote-fetch functions such as nvm_ls_remote (lines 851–857) and install logic (lines 3875–3895) to filter release lists before download.

NVM_DEFAULT_PACKAGE_FILE

While primarily internal, NVM_DEFAULT_PACKAGE_FILE resolves to $NVM_DIR/default-packages. During nvm install (lines 4572–4588), nvm reads this file line-by-line and runs npm install -g for each package automatically after installing a new Node version.

Download Mirrors and Authentication

NVM_NODEJS_ORG_MIRROR and NVM_IOJS_ORG_MIRROR

NVM_NODEJS_ORG_MIRROR sets an alternate URL for official Node binaries, while NVM_IOJS_ORG_MIRROR provides the same for historic io.js binaries (maintained for backward compatibility).

Both are validated and consumed in nvm_get_mirror at lines 2225–2227 to construct the final download URL. If unset, nvm defaults to https://nodejs.org/dist.

NVM_AUTH_HEADER

NVM_AUTH_HEADER supplies an HTTP Authorization header value passed to curl or wget when fetching binaries from private mirrors. The value is sanitized via nvm_sanitize_auth_header and injected into download commands at lines 123–124 and 151–152 in the nvm_download function.

Runtime Path and Symlink Management

NVM_BIN and NVM_INC

After a successful nvm use, the script exports NVM_BIN and NVM_INC at lines 3969–3970. These point to the active version's bin/ and include/node/ directories respectively, allowing downstream commands like npm and node-gyp to locate executables and headers without hardcoded paths.

NVM_SYMLINK_CURRENT

When NVM_SYMLINK_CURRENT is set to true, nvm use creates or updates a current symlink inside $NVM_DIR pointing to the active version. This is implemented in nvm_use at lines 3861–3870 and is particularly useful for IDEs that expect a fixed path to the Node executable.

Output Formatting and Debugging

NVM_COLORS and NVM_NO_COLORS

NVM_COLORS enables colorized output for commands like nvm ls. It is exported by the --no-colors flag handler at lines 1050–1052. NVM_NO_COLORS serves as an internal synonym used when color detection is forced off (e.g., in CI environments).

The printing helper nvm_print_versions checks these variables at lines 4172–4175 to determine whether to apply ANSI color codes.

NVM_DEBUG

Setting NVM_DEBUG=1 activates diagnostic mode. The core script prints a snapshot of the active environment (current node, npm, npm config prefix) at lines 222–226 and runs a detailed dump at lines 3324–3327. In this mode, npm commands are prefixed with nvm_echo for transparency.

Preventing Configuration Conflicts

PREFIX Variables

nvm explicitly guards against PREFIX, NPM_CONFIG_PREFIX, and npm_CONFIG_PREFIX at lines 2836–2838 and 2860–2862. If any are set, nvm aborts with a clear error message because these variables interfere with nvm's path-rewriting logic and can break version switching.

How nvm Uses These Variables Internally

The variable lifecycle follows a strict flow through the codebase:

1. Sourcing phase – nvm.sh detects and exports $NVM_DIR, then establishes defaults for flags and colors.

2. Version resolution – Functions like nvm_resolve_alias, nvm_version_path, and nvm_remote_version read $NVM_LTS and mirror variables to build correct URL lists and filter LTS releases.

3. Downloading – nvm_download assembles curl/wget commands, appending $NVM_AUTH_HEADER after sanitization. Mirror URLs are derived from $NVM_NODEJS_ORG_MIRROR or fall back to the official Node.js registry.

4. Path manipulation – nvm_change_path rewrites $PATH, $MANPATH, and $NODE_PATH, then exports $NVM_BIN and $NVM_INC for subprocess visibility. If $NVM_SYMLINK_CURRENT is true, the symlink is updated via nvm_use.

5. Execution – Color variables control output formatting in printing helpers, while $NVM_DEBUG triggers diagnostic dumps without altering normal operation.

Practical Configuration Examples

Use a Corporate Mirror for Faster Downloads

export NVM_NODEJS_ORG_MIRROR=https://cdn.mycompany.com/nodejs
nvm install --lts

The variable is read in nvm_get_mirror (line 2225).

Enable the Current Symlink for IDE Integration

export NVM_SYMLINK_CURRENT=true
nvm use 20

# IDE can now reference $NVM_DIR/current/bin/node

See symlink creation in nvm_use (lines 3861–3870).

Debug Unexpected PATH Behavior

export NVM_DEBUG=1
nvm use 18

# Outputs internal state including PATH, NODE_PATH, and MANPATH

Debug block starts at line 222; detailed dump at lines 3324–3327.

Disable Colors in CI Logs

export NVM_NO_COLORS=1
nvm ls

Color checks appear in nvm_print_versions (line 4172).

Auto-Install Default Global Packages

cat <<EOF > "$NVM_DIR/default-packages"
typescript
eslint
prettier
EOF

nvm install 20

# Automatically runs npm install -g for each listed package

Handled inside nvm install (lines 4572–4588).

Summary

• NVM_DIR is the foundational variable that determines where all versions and aliases are stored, auto-detected at script load time.
• Mirror variables (NVM_NODEJS_ORG_MIRROR, NVM_IOJS_ORG_MIRROR) and NVM_AUTH_HEADER control how binaries are fetched from private or corporate registries.
• Path exports (NVM_BIN, NVM_INC, NVM_SYMLINK_CURRENT) manage runtime environment setup and IDE compatibility.
• Debugging and output are controlled by NVM_DEBUG, NVM_COLORS, and NVM_NO_COLORS, with checks scattered across printing helpers.
• Conflict prevention ensures PREFIX and NPM_CONFIG_PREFIX are unset to avoid path corruption.

Frequently Asked Questions

How do I change the default installation directory for nvm?

Set the NVM_DIR environment variable before sourcing nvm.sh. According to lines 447–460 in nvm.sh, if NVM_DIR is already defined, nvm preserves your setting; otherwise it auto-detects based on the script location. All subsequent operations—version installs, alias storage, and cache—reference this root path.

Why does nvm exit with an error about NPM_CONFIG_PREFIX?

nvm aborts execution if it detects NPM_CONFIG_PREFIX, PREFIX, or npm_CONFIG_PREFIX (lines 2836–2838 and 2860–2862). These variables override npm's global package location and break nvm's ability to switch between Node versions cleanly. Unset them in your shell profile before sourcing nvm.

Can I use nvm with a private Node.js mirror requiring authentication?

Yes. Export NVM_NODEJS_ORG_MIRROR with your internal CDN URL and NVM_AUTH_HEADER with your HTTP Authorization token. The nvm_download function sanitizes the header via nvm_sanitize_auth_header and injects it into curl/wget commands at lines 123–124 and 151–152.

What is the difference between NVM_COLORS and NVM_NO_COLORS?

NVM_COLORS is the primary user-facing variable toggled by the --no-colors flag (lines 1050–1052), while NVM_NO_COLORS serves as an internal override for CI environments where color detection must be forced off. Both are checked in output functions like nvm_print_versions (line 4172) to determine whether to strip ANSI codes from the output.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}