NVM for Windows — User Guide

NVM for Windows (nvm) is a command-line tool that lets you install, switch between, and manage multiple versions of Node.js on a single Windows computer. It is the Node.js version manager recommended by Microsoft, npm, and Google for Windows users. Written in Go, it does not depend on an existing Node.js installation and uses a single Windows symlink to "hot-switch" the active version across every open terminal at once.

Important

This is not the same project as the Unix nvm (nvm-sh/nvm). It is a separate Windows-only tool with a different design. Commands look similar but are not identical — follow this guide, not Unix nvm documentation.

1. Quick Start

Get up and running in four steps.

1. Uninstall any existing Node.js from your machine (recommended — see Before You Install).
2. Run the installer from the releases page and accept the defaults.
3. Open a new terminal as Administrator (Command Prompt or PowerShell).
4. Install and activate the latest Node.js:

nvm install latest
nvm use latest

Downloading node.js version 22.14.0 (64-bit)...
Complete
Installation complete. If you want to use this version, type

nvm use 22.14.0

Now using node v22.14.0 (64-bit)

Verify it worked:

node -v

v22.14.0

Warning

NVM for Windows must run in an Administrator shell. Creating and swapping the symlink it uses requires elevated rights. If nvm use appears to do nothing, you are almost certainly running a non-elevated terminal or have a conflicting Node.js installation. See Troubleshooting.

2. Installation

2.1 Install with the official installer (recommended)

Download the latest nvm-setup.exe from the releases page. The installer bundles an uninstaller and configures two environment variables for you:

• NVM_HOME — where NVM for Windows stores each Node.js version and its settings.txt.
• NVM_SYMLINK — the symlink placed on your system PATH; its target is swapped when you run nvm use.

Note

If NVM for Windows doesn't appear to work immediately after installation, restart your terminal (not the whole computer). The new PATH entries are only picked up by newly opened shells.

2.2 Choosing install locations

Accept the defaults unless you have a reason not to. Two rules matter:

• NVM_SYMLINK must point to a path that does not already exist — a symlink cannot overwrite a physical directory. The default C:\nvm\node (or similar) is safe; C:\Program Files\nodejs is not if that folder already exists.
• NVM_HOME and NVM_SYMLINK must be different locations.

Caution

Do not point NVM_SYMLINK at an existing Node.js directory such as C:\Program Files\nodejs. The installation will fail because Windows will not let a symlink replace a real folder. Pick a fresh path like C:\nvm\node.

2.3 Verify the installation

Open a new Administrator terminal and run the built-in troubleshooter:

nvm debug

Running NVM for Windows with administrator privileges.

Windows Version:        10.0 (Build 22631)

NVM4W Version:          1.2.2
NVM4W Path:             C:\nvm
NVM4W Settings:         C:\nvm\settings.txt
NVM_HOME:               C:\nvm
NVM_SYMLINK:            C:\nvm\node
Node Installations:     C:\nvm
Default Architecture:   64-bit

Total Node.js Versions: 1
Active Node.js Version: v22.14.0

No problems detected.

If nvm debug reports No problems detected., you are ready to go. If it lists problems, jump to Troubleshooting.

3. Before You Install (Read This)

NVM for Windows works best on a machine with no other Node.js installation. The single most common source of problems is a leftover system-wide Node.js fighting NVM4W for control of PATH.

Tip

The simplest, most reliable setup is: uninstall every existing Node.js installation first, then install NVM for Windows. This avoids every pitfall below.

If you cannot remove your existing Node.js (for example, a heavily customized corporate install):

• NVM for Windows can assume management of an existing installation, but the results depend entirely on the permissions of the account running the installer.
• For security reasons, Windows will not let the NVM4W installer uninstall a Node.js package published by a different vendor. Instead, the installer copies your existing Node.js files (including global npm modules and configuration) into the NVM root so you can safely uninstall the original afterward.

Back up your global npm config before installing:

• Copy %AppData%\npm\etc\npmrc somewhere safe, or move its settings into your user config at %UserProfile%\.npmrc.
• Delete the old global install location (e.g. %AppData%\npm) to prevent global-module conflicts.
• Delete any remaining Node.js install directories such as %ProgramFiles%\nodejs. NVM's symlink will refuse to overwrite an existing (even empty) directory there.

Warning

If you leave an old Node.js installation in place, running nvm use may silently appear to do nothing, and node -v will always report the old version. This is a PATH conflict. Run nvm debug to confirm it.

4. Everyday Usage

All commands run as nvm <command>. Type nvm with no arguments at any time to print the built-in help.

4.1 Installing Node.js versions

nvm install <version> [arch]

The <version> can be:

The optional [arch] is 32, 64, arm64, or all (install both 32-bit and 64-bit). If omitted, NVM uses your system's default architecture.

nvm install lts
nvm install 18.20.4 32
nvm install latest all

Tip

nvm install is aliased to nvm i. Most commands have short aliases — see the Command Reference.

Note

Each install downloads Node.js and its matching npm separately, so a single nvm install gives you a fully working node + npm pair.

If your download server uses a self-signed or otherwise unverifiable certificate, append --insecure to bypass SSL validation:

nvm install 20.11.1 --insecure

WARNING: The remote SSL certificate will not be validated during the download process.

Caution

--insecure disables certificate verification for the download. Use it only on networks you trust (for example, behind a corporate proxy with TLS interception). It is not the default for good reason.

4.2 Switching the active version

nvm use <version> [arch]

nvm use swaps the symlink so every open terminal immediately points at the chosen version — you do not need to re-run it per terminal, and the choice persists across reboots.

nvm use 22.14.0
nvm use lts
nvm use newest

The version argument also accepts the aliases latest, lts, and newest (the highest version you already have installed). You can switch architecture without changing version by passing only an arch:

nvm use 64

Now using node v22.14.0 (64-bit)

Note

nvm use is aliased to nvm u. If the requested version isn't installed, NVM tells you — and if the same version exists in a different architecture, it suggests the exact command to use it.

4.3 Listing versions

nvm list            # versions installed on this machine (alias: nvm ls)
nvm list available  # a table of versions available for download

The installed list marks the active version with *:

  * 22.14.0 (Currently using 64-bit executable)
    20.11.1
    18.20.4

nvm list available prints a table of Current, LTS, Old Stable, and Old Unstable releases:

|   CURRENT  |    LTS     | OLD STABLE | OLD UNSTABLE |
|------------|------------|------------|--------------|
|  23.7.0    |  22.14.0   |  0.12.18   |   0.11.16    |
|  ...       |  ...       |  ...       |   ...        |

This is a partial list. For a complete list, visit https://nodejs.org/en/download/releases

4.4 Checking what's active

nvm current   # the version currently in use
nvm arch      # whether node is running in 32 or 64 bit mode

v22.14.0

4.5 Removing versions

nvm uninstall <version>   # remove one version (alias: nvm rm)
nvm reinstall <version>   # clean-remove, then install again from scratch

reinstall is a shortcut for fixing a corrupted install: it removes the version (and its symlink if active) and then downloads it fresh.

4.6 Turning version management on and off

nvm on    # enable Node.js version management
nvm off   # disable it (does NOT uninstall anything)

nvm off removes the active symlink so that node is no longer resolved through NVM. It leaves all installed versions in place; run nvm on to re-enable.

5. Common Tasks

5.1 Reinstall your global tools after switching

Global npm packages are not shared between Node.js versions. Each version has its own global module space, so after switching you must reinstall the global tools you rely on:

nvm use 22.14.0
npm install -g yarn

nvm use 20.11.1
npm install -g yarn

Warning

Global npm modules installed under one Node version are invisible to other versions. Reinstall them per version. Some modules also may not support every Node version — stay aware of your active version as you work.

5.2 Use Yarn with NVM for Windows

npm i -g yarn

Install Yarn globally for each Node version you intend to use it with. See the project wiki for details.

5.3 Set a download proxy

If you are behind a corporate proxy:

nvm proxy http://proxy.mycompany.com:8080   # set a proxy
nvm proxy                                    # show the current proxy
nvm proxy none                               # remove the proxy

If you omit the scheme, http:// is added automatically.

5.4 Use a regional download mirror

Users in regions where nodejs.org is slow or blocked can redirect downloads to a mirror:

nvm node_mirror https://npmmirror.com/mirrors/node/
nvm npm_mirror https://npmmirror.com/mirrors/npm/

5.5 Change where versions are stored

nvm root <path>   # set the storage root
nvm root          # show the current root

5.6 Subscribe to desktop notifications

NVM for Windows can notify you when new Node.js or NVM4W releases appear:

nvm subscribe lts
nvm subscribe current
nvm unsubscribe lts

Valid topics are lts, current, nvm4w, and author. Subscriptions register lightweight Windows scheduled tasks that check for updates in the background and raise a toast notification.

Note

Desktop notifications and subscriptions are delivered through a companion helper (author-nvm.exe) installed alongside nvm. If nvm debug reports that the author bridge is missing, notifications will not work, but all core version-management commands still function normally.

6. Keeping NVM for Windows Up to Date

From v1.1.8 onward, NVM for Windows can update itself:

nvm upgrade

upgrading from v1.2.2-->1.2.3
downloading...
verifying checksum...
extracting update...
applying update...
Upgrade complete

The upgrade downloads the latest release, verifies its checksum, backs up your current installation, and swaps in the new binaries. Your installed Node.js versions are never touched.

Important

A backup of the previous NVM4W binaries is created automatically and retained for 7 days under a hidden .update folder. After 7 days it is removed by a scheduled cleanup task.

You can also upgrade by simply re-running the latest installer from the releases page — point it at the same install and symlink folders you used originally.

7. How It Works (the short version)

You don't need to understand the internals to use NVM for Windows, but one concept explains most of its behavior.

NVM for Windows keeps every Node.js version in its own folder under NVM_HOME (for example C:\nvm\v22.14.0, C:\nvm\v20.11.1). A single symlink — NVM_SYMLINK — is placed on your system PATH exactly once, when you install. When you run nvm use 20.11.1, NVM simply re-points that symlink at the v20.11.1 folder.

Because the symlink (not the version folders) is what's on your PATH, the switch takes effect everywhere instantly, survives reboots, and never requires editing PATH again. The catch is that creating and modifying a symlink on Windows requires Administrator rights or Windows Developer Mode — which is why NVM for Windows must run elevated.

Tip

If you'd rather not run as Administrator, enable Windows Developer Mode (Settings → Privacy & Security → For developers). With it on, most nvm commands work without elevation, as long as your account can modify the symlink location. nvm debug reports your Developer Mode status.

8. Troubleshooting

Run nvm debug first — it checks for PATH conflicts, permission problems, broken symlinks, missing files, and connectivity issues, and prints a PROBLEMS DETECTED section with specifics.

Error: node -v shows the wrong version after nvm use

Cause: A separate Node.js installation is on your PATH ahead of the NVM symlink (a PATH conflict). nvm use swaps the symlink, but the other install shadows it.

Solution: Uninstall the conflicting Node.js, then delete any leftover folder such as %ProgramFiles%\nodejs and %AppData%\npm. Run nvm debug to confirm the conflict is gone.

Prevention: Remove all existing Node.js installations before installing NVM for Windows.

Error: nvm use appears to do nothing

Cause: You are running a non-elevated terminal, so NVM cannot modify the symlink; or a PATH conflict (above) is masking the change.

Solution: Re-open the terminal as Administrator, or enable Windows Developer Mode. Then run nvm use <version> again.

Error: failed to elevate permissions to create symlink

Cause: NVM could not obtain the rights needed to create or replace the symlink.

Solution: Start Command Prompt or PowerShell with Run as administrator and retry. If your environment blocks elevation via group policy, enable Developer Mode instead.

Error: NVM_SYMLINK is set to a physical file/directory at <path>

Cause: Something replaced the symlink location with a real folder or file (often a manual edit to settings.txt, or another installer recreating C:\Program Files\nodejs).

Solution: Remove that physical directory/file, or change NVM_SYMLINK to a different path that does not already exist, then run nvm use again. This guard exists to prevent NVM from deleting real data.

Error: open \settings.txt: The system cannot find the file specified.

Cause: The NVM_HOME environment variable is empty or wrong, so NVM is looking for settings.txt at the filesystem root.

Solution: Confirm NVM_HOME points at your NVM install directory (run nvm debug to see its value), then restart your terminal so the corrected variable is loaded.

Error: Version <x> is not available.

Cause: The requested version does not exist on the download server (a typo, a not-yet-released version, or an architecture that version was never published for — e.g. arm64 builds only exist from Node 19.9+, and 64-bit builds only from Node 8+).

Solution: Run nvm list available, or visit https://nodejs.org/dist/ to confirm the version and architecture exist. If you just saw the release announced, wait ~15 minutes and try again.

Error: installing npm fails, or npm disappears after installing a package

Cause: A known issue where installing a module right after a Node install can disrupt npm (GitHub #606), often tied to special characters in your user-profile path or to leftover global-npm state.

Solution: Run nvm reinstall <version> to rebuild the version cleanly. Ensure your Windows username/profile path contains no unusual characters, and that you removed any old %AppData%\npm before installing NVM4W.

Error: antivirus blocks installation or VBScript

Cause: Some antivirus products (notably McAfee) interfere with the VBScript engine NVM uses for elevation (GitHub #133).

Solution: Temporarily allow NVM for Windows in your antivirus, or follow the resolution in issue #133. Note that signed releases (all except v1.1.8) reduce antivirus false positives.

Error: The author-nvm.exe file is missing or not executable.

Cause: The notification companion helper isn't present.

Solution: Reinstall NVM for Windows using the official installer. Core commands still work without it — only desktop notifications and subscribe are affected.

Downloads are extremely slow

Cause: IPv6 connectivity to nodejs.org has been observed to slow downloads dramatically.

Solution: nvm debug reports whether IPv6 is enabled. Consider configuring a faster regional mirror with nvm node_mirror (see section 5.4).

9. Command Reference

Tip

Add verbose to (almost) any command to enable detailed debug logging — useful when reporting a bug.

10. Frequently Asked Questions

Q: Is this the same as the nvm I use on Mac/Linux? No. NVM for Windows is a separate, Windows-only project written in Go. It shares the name and a similar command style, but the implementation and some behaviors differ. Don't follow Unix nvm docs here.

Q: Do I need to run nvm use in every new terminal? No. Because NVM swaps a single symlink that lives on your system PATH, one nvm use applies to all open terminals and persists across reboots. You only run nvm use when you want to change versions.

Q: Why must I run as Administrator? Creating and re-pointing a Windows symlink requires elevated rights. The alternative is enabling Windows Developer Mode, which allows symlink changes without full elevation.

Q: Why did node -v not change after nvm use? Almost always a PATH conflict from a separate Node.js installation that sits ahead of the NVM symlink. Uninstall the other Node.js and run nvm debug.

Q: Are my global npm packages shared across versions? No. Each Node.js version has its own global module space. Reinstall global tools (like yarn) for each version you use.

Q: Can I install both 32-bit and 64-bit of a version? Yes — nvm install <version> all. Then switch architecture for the active version with nvm use <version> 32 or nvm use <version> 64.

Q: How do I install the newest LTS? nvm install lts then nvm use lts.

Q: What's the difference between latest and newest in nvm use? latest resolves to the newest release available for download. newest resolves to the highest version you already have installed locally.

Q: Does NVM for Windows support arm64 (Windows on ARM)? Yes for downloading arm64 Node.js builds, which exist from Node 19.9 onward. Use nvm install <version> arm64.

Q: How do I downgrade or roll back an NVM upgrade? nvm upgrade keeps a backup of the previous binaries for 7 days under a hidden .update folder. If you need an older NVM4W release, download it directly from the releases page and run that installer.

Q: I get checksum or download errors during nvm upgrade. What now? This usually means a network interruption or a proxy stripping the download. Retry on a stable connection; configure nvm proxy if you're behind a corporate proxy; or download and run the installer manually from the releases page.

Q: Where are my settings stored? In settings.txt inside your NVM_HOME directory. It records your root, default architecture, proxy, and mirror choices. You normally never edit it by hand — use the nvm commands instead.

Q: My antivirus flags nvm. Is it safe? Releases are code-signed (all except v1.1.8, whose certificate had expired) to minimize false positives. If your AV manipulates the VBScript engine, see GitHub issue #133.

Q: Which terminals are supported? Command Prompt and PowerShell are the officially supported consoles. Others (Git Bash, ConEmu, etc.) may work but some features — particularly elevation and colored output — can behave differently.