Version Resolution
NVM for Windows accepts several ways to identify a Node.js version. Depending on the context, an input can name one release, identify a release line, or describe a range of acceptable releases. NVM for Windows resolves that input to a concrete Node.js version before performing an operation.
There are two kinds of version input:
- A version specifier is an operational command-line argument.
- A version constraint describes acceptable versions in a project file.
Version specifiers
Version specifiers are tokens passed to commands such as install, use, and
uninstall.
| Form | Example | Resolution |
|---|---|---|
| Latest release | latest | Newest available release from the mirror index. |
| Latest LTS | lts | Newest available LTS release. |
| Named LTS line | lts/iron | Newest release from the named LTS line. |
| User alias | legacy | Version assigned with nvm alias add. |
| Major only | 24 | Newest matching 24.x.x release. |
| Major.minor | 24.1 | Newest matching 24.1.x release. |
| Exact version | 24.1.0, v24.1.0 | The specified release. The v prefix is optional. |
Commands that accept version specifiers include:
Examples
# reserved aliases
nvm install lts
nvm use latest
# named LTS line
nvm install lts/iron
# partial and exact versions
nvm use 24.1
nvm cache add 22.14.0
# user-defined alias
nvm alias add stable 24.1.0
nvm use stable
Version constraints
Version constraints describe acceptable releases in project pinning and auto-detect files. Unlike a command-line specifier, a constraint can match a range of releases.
| Constraint | Example | Meaning |
|---|---|---|
| Caret | ^18 | Compatible with major 18. |
| Tilde | ~20.1 | Compatible with minor 20.1. |
| Minimum | >=16 | Version 16 or newer. |
| Range | >=18 <21 | Version 18 or newer, but older than version 21. |
| Wildcard | 18.x | Any release in the 18.x line. |
| Any | * | Any version. |
| Exact | 24.1.0 | Only the specified release. |
Constraints can appear in the following project files:
| Source | Typical content | Behavior |
|---|---|---|
.nvmrc | Exact version or constraint | Auto-detection resolves a matching version. |
.node-version | Exact version or constraint | Uses the same resolution path as .nvmrc. |
package.json engines.node | Exact version or semver constraint | Auto-detection resolves a version satisfying the Node.js engine constraint. |
Configured auto-detect files come from auto_detect. By default, NVM for Windows checks
.nvmrc, .node-version, and package.json.
Resolution order
- User alias mapping (from
nvm alias add) - Reserved aliases (
latest,lts,lts/<codename>) - Partial versions expanded to the best matching concrete release
- Semver constraints resolved in constraint-aware flows (for example
engines.nodeor caret/tilde ranges in detect files) - Read version string from the configured detect file in the current directory tree (auto-detect)
- Apply
auto_use,auto_install, and related config when switching or installing
Auto-detect Node.js version by project
In shim mode, NVM for Windows resolves the Node.js version from an auto-detect file (.nvmrc, .node-version, package.json, etc.). If no version can be resolved, it falls back to the default system version.
Pinning a Node.js version to a project
nvm pin creates auto-detect files automatically. It accepts a version specifier, resolves it, and
writes the exact version to the auto-detect file.
# set the active version, then pin .nvmrc
nvm use 24
nvm pin 24 --file=.nvmrc
# set package.json engines.node, engines.npm, and the equivalent devEngines properties
nvm pin 24 --file=package.json