Operating Modes
NVM for Windows operates in one of two modes: link or shim. These modes are responsible for This mode can be toggled at any time.
# Easy access
nvm use shim
nvm use link
# Also available in the nvm configuration
nvm cfg set mode=shim
nvm cfg set mode=link
Link Mode
This mode uses links to locate the active system-wide version of node.exe. The .nodejs target is updated any time nvm use changes the default version.
Link mode offers the closest possible experience to running node.exe "as delivered" by nodejs.org. This mode offers zero latency. Link mode, by its nature, does not provide any advanced modern workflow features (shim mode does).
Version 2.0.0 introduced the "fallback" link creation strategy.
NTFS Junctions do not require special permissions, but will not work with UNC paths (like remote network shares). If you attempt to link to a UNC path, nvm-windows attempts to create a symlink instead of a junction. Symlinks require special permissions.
Creation of symlinks requires SeCreateSymbolicLinkPrivilege. This is granted when Developer Mode is enabled (recommended), or for administrators. It can also be granted through Group Policies.
Unlike prior versions, NVM for Windows will not attempt to elevate permissions (i.e. no UAC prompt) on failure of symlink creation. If permissions block the creation of a link, the user is notified (desktop notification).
Shim Mode (default)
Shim mode offers a streamlined developer experience. The tradeoff is addtional latency (~25-35ms total).
Most users won't notice or feel the impact of shim latency, but may feel the impact of a workflow encumbered by esoteric permission requirements. Shim mode is recommended for most users.
Shim mode offers:
- Directory/project-level version detection via
.nvmrc,.node-version,package.json, or other custom run command files. - Automatic installations of missing versions.
Windows has a "universal latency tax". It uses CreateProcessW to launch any executable. This tax is paid when the shim is launched and again when the shim runs node.exe. On average, CreateProcessW takes 15ms. The shim adds 1-3ms to identify the desired Node.js version and securely relay the command.
15ms (shim CreateProcessW) + 3ms (shim logic) + 15ms (shim CreateProcessW) = 33ms
Comparison
| Link | Shim | |
|---|---|---|
| Latency1 | 0ms | 25-35ms |
| System Version | ✔️ | ✔️ |
| Automatic Installtion | ✔️ | ✔️ |
| Automatic Version Detection | ❌ | ✔️ |
| Special Permissions | SeCreateSymbolicLinkPrivilegefor UNC paths symlinks | None |