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

> Learn how NVM_RC_VERSION dynamically sets your Node.js version using .nvmrc files. Effortlessly manage project-specific Node.js environments with nvm.

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

---

**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`](https://github.com/nvm-sh/nvm/blob/main/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:

```sh
NVMRC_PATH="$(nvm_find_nvmrc)"

```

This implementation resides at **[nvm.sh: lines 607-608](https://github.com/nvm-sh/nvm/blob/master/nvm.sh#L607-L608)**. 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:

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

```

Implemented at **[nvm.sh: lines 616-620](https://github.com/nvm-sh/nvm/blob/master/nvm.sh#L616-L620)**, the parser uses sed to clean the input:

```sh
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](https://github.com/nvm-sh/nvm/blob/master/nvm.sh#L35-L102)**, 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:

```sh
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](https://github.com/nvm-sh/nvm/blob/master/nvm.sh#L604-L629)**, 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](https://github.com/nvm-sh/nvm/blob/master/nvm.sh#L3898-L3903)** checks `NVM_RC_VERSION` before falling back to the currently active version. This allows seamless context switching between projects:

```sh
$ 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](https://github.com/nvm-sh/nvm/blob/master/nvm.sh#L3487-L3493)**, the logic detects when no version argument is provided and substitutes `NVM_RC_VERSION`:

```sh

# .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](https://github.com/nvm-sh/nvm/blob/master/nvm-exec#L13)**, it sources the version before delegation:

```sh
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:

```sh
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`](https://github.com/nvm-sh/nvm/blob/main/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](https://github.com/nvm-sh/nvm/blob/master/README.md#L841)** 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.