What Is NVM_RC_VERSION and How It Enables .nvmrc File Tracking in nvm

NVM_RC_VERSION is the environment variable that nvm populates with the version string extracted from a .nvmrc file, serving as the bridge between project-specific Node.js version declarations and command execution.

When you work across multiple Node.js projects, the .nvmrc file lets you pin each repository to a specific runtime version. The NVM_RC_VERSION variable captures the parsed content of that file, enabling the nvm-sh/nvm toolchain to automatically switch, install, or execute commands against the correct Node.js version without explicit version arguments.

The Discovery and Parsing Pipeline

The journey from a plain-text .nvmrc file to an active Node.js version follows a strict pipeline implemented in nvm.sh. Each stage prepares the version string for consumption by downstream commands.

Locating the .nvmrc File

Nvm first searches for a version file by walking up the directory tree from your current working directory. The nvm_find_nvmrc function handles this traversal:

NVMRC_PATH="$(nvm_find_nvmrc)"

This implementation resides at nvm.sh: lines 607-608. When found, the path is stored in NVMRC_PATH for the next stage.

Parsing and Sanitizing the Version String

Once located, the file content passes through nvm_process_nvmrc to extract a valid version identifier. This function strips comments, trims whitespace, and validates syntax:

if ! NVM_RC_VERSION="$(nvm_process_nvmrc "${NVMRC_PATH}")"; then
    return 1
fi

Implemented at nvm.sh: lines 616-620, the parser uses sed to clean the input:

lines=$(command sed 's/#.*//' "$NVMRC_PATH" | command sed 's/^[[:space:]]*//;s/[[:space:]]*$//' | nvm_grep -v '^$')

The full parser logic spans nvm.sh: lines 35-102, handling edge cases like key-value pairs and bare version strings.

Exporting NVM_RC_VERSION

The nvm_rc_version helper function orchestrates the lookup and exports the result:

export NVM_RC_VERSION=''

# ... discovery and parsing logic ...

nvm_echo "Found '${NVMRC_PATH}' with version <${NVM_RC_VERSION}>"

Found at nvm.sh: lines 604-629, this function ensures NVM_RC_VERSION contains only the sanitized version string when valid, or returns a non-zero exit code if the file is empty or malformed.

How nvm Commands Consume NVM_RC_VERSION

Commands throughout the nvm suite read NVM_RC_VERSION to determine which Node.js version to target when the user omits an explicit version argument.

Automatic Version Selection with nvm use

When you run nvm use without arguments, the implementation at nvm.sh: lines 3898-3903 checks NVM_RC_VERSION before falling back to the currently active version. This allows seamless context switching between projects:

$ nvm use
Found '/path/to/project/.nvmrc' with version <14.21.3>
Now using node v14.21.3 (npm v6.14.17)

Behind the scenes, nvm use calls nvm_rc_version, which sets NVM_RC_VERSION=14.21.3, then invokes nvm_ensure_version_installed "$NVM_RC_VERSION".

Installing from .nvmrc with nvm install

The nvm install command behaves similarly. At nvm.sh: lines 3487-3493, the logic detects when no version argument is provided and substitutes NVM_RC_VERSION:

# .nvmrc contains "16.20.0"

$ nvm install
Found '/path/to/project/.nvmrc' with version <16.20.0>
Downloading and installing node v16.20.0...
Now using node v16.20.0 (npm v8.19.4)

This pattern ensures that nvm install without arguments always respects the project's declared version constraint.

Executing Commands via nvm exec

The wrapper script nvm-exec leverages the same mechanism to run arbitrary commands under the .nvmrc version. At nvm-exec: line 13, it sources the version before delegation:

nvm_rc_version > /dev/null && nvm_ensure_version_installed "$NVM_RC_VERSION"

This guarantees that nvm exec node -v automatically uses the version specified in your nearest .nvmrc, regardless of your globally active Node.js version.

Error Handling and Scope Management

Nvm implements strict hygiene around NVM_RC_VERSION to prevent state leakage between commands.

If nvm_process_nvmrc encounters an empty file or syntax violation, it triggers nvm_nvmrc_invalid_msg and returns a non-zero exit code. This prevents NVM_RC_VERSION from being set with invalid data.

After consumption, commands typically unset the variable to avoid polluting the environment for subsequent operations:

unset NVM_RC_VERSION

Additionally, the export only occurs when NVM_SILENT is not set, keeping quiet mode output clean while preserving functionality.

Summary

• NVM_RC_VERSION is the environment variable that stores the parsed version string from .nvmrc files.

• The variable gets populated by nvm_rc_version in nvm.sh, which uses nvm_find_nvmrc (line 607) to locate the file and nvm_process_nvmrc (lines 35-102) to sanitize the content.

• Commands like nvm use (lines 3898-3903), nvm install (lines 3487-3493), and nvm exec (via nvm-exec line 13) read NVM_RC_VERSION when no explicit version argument is provided.

• The implementation includes validation to prevent malformed files from setting the variable, and actively unsets the variable after use to maintain clean shell state.

Frequently Asked Questions

What happens if I run nvm use without a .nvmrc file?

If no .nvmrc file exists in the current directory or any parent directory, nvm_find_nvmrc returns empty, nvm_rc_version fails silently or with a warning, and nvm use falls back to your default alias or currently active version. The command will not switch versions if it cannot locate a version file.

Can I manually set NVM_RC_VERSION instead of using a file?

While you can manually export NVM_RC_VERSION in your shell session, nvm will overwrite this value whenever you run commands that invoke nvm_rc_version. For persistent per-project configuration, creating a .nvmrc file is the supported approach according to the README.md documentation.

Why does nvm unset NVM_RC_VERSION after using it?

Nvm unsets NVM_RC_VERSION after command execution to prevent the variable from leaking into subsequent shell operations. This ensures that running nvm use in one directory does not accidentally influence nvm install run later in a different directory without an .nvmrc file.

How does nvm handle comments or whitespace in .nvmrc?

The nvm_process_nvmrc function uses sed to strip comments (everything after #) and trim leading and trailing whitespace before validating the version string. This allows you to document your version choices within the .nvmrc file without breaking the parsing logic.

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