# 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](https://github.com/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](#3-before-you-install-read-this)). 2. **Run the installer** from the [releases page](https://github.com/coreybutler/nvm-windows/releases) and accept the defaults. 3. **Open a new terminal as Administrator** (Command Prompt or PowerShell). 4. **Install and activate the latest Node.js:** ```bash nvm install latest nvm use latest ``` ```text 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: ```bash node -v ``` ```text 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](#8-troubleshooting). --- ## 2. Installation ### 2.1 Install with the official installer (recommended) Download the latest `nvm-setup.exe` from the [releases page](https://github.com/coreybutler/nvm-windows/releases). 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: ```bash nvm debug ``` ```text 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](#8-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 `. Type `nvm` with no arguments at any time to print the built-in help. ### 4.1 Installing Node.js versions ```bash nvm install [arch] ``` The `` can be: | Value | Meaning | |-------|---------| | `22.14.0` | An exact version | | `22` or `22.14` | A partial version — the latest matching patch is resolved for you | | `latest` (or `node`) | The newest current release | | `lts` | The most recent Long-Term Support release | 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. ```bash 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](#9-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: ```bash nvm install 20.11.1 --insecure ``` ```text 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 ```bash nvm use [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. ```bash 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: ```bash nvm use 64 ``` ```text 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 ```bash 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 `*`: ```text * 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: ```text | 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 ```bash nvm current # the version currently in use nvm arch # whether node is running in 32 or 64 bit mode ``` ```text v22.14.0 ``` ### 4.5 Removing versions ```bash nvm uninstall # remove one version (alias: nvm rm) nvm reinstall # 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 ```bash 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: ```bash 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 ```bash npm i -g yarn ``` Install Yarn globally for each Node version you intend to use it with. See the project [wiki](https://github.com/coreybutler/nvm-windows/wiki/Common-Issues#how-do-i-use-yarn-with-nvm-windows) for details. ### 5.3 Set a download proxy If you are behind a corporate proxy: ```bash 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: ```bash nvm node_mirror https://npmmirror.com/mirrors/node/ nvm npm_mirror https://npmmirror.com/mirrors/npm/ ``` | Command | Default if left blank | Common mirror (e.g. China) | |---------|-----------------------|----------------------------| | `nvm node_mirror [url]` | `https://nodejs.org/dist/` | `https://npmmirror.com/mirrors/node/` | | `nvm npm_mirror [url]` | `https://github.com/npm/cli/archive/` | `https://npmmirror.com/mirrors/npm/` | ### 5.5 Change where versions are stored ```bash nvm root # 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: ```bash 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: ```bash nvm upgrade ``` ```text 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](https://github.com/coreybutler/nvm-windows/releases) — 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 ` 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 ` **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 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](https://github.com/coreybutler/nvm-windows/issues/606)), often tied to special characters in your user-profile path or to leftover global-npm state. **Solution:** Run `nvm reinstall ` 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](https://github.com/coreybutler/nvm-windows/issues/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](#54-use-a-regional-download-mirror)). --- ## 9. Command Reference | Command | Alias | Description | |---------|-------|-------------| | `nvm arch [32\|64\|arm64]` | | Show whether Node runs in 32/64/arm64 mode. Pass a value to set the default architecture. | | `nvm current` | | Display the active Node.js version. | | `nvm debug` | | Run the built-in troubleshooter against your environment. | | `nvm install [arch]` | `nvm i` | Install a version. `arch` = `32`/`64`/`arm64`/`all`. Add `--insecure` to skip SSL validation. | | `nvm list [available]` | `nvm ls` | List installed versions, or `available` to see what can be downloaded. | | `nvm on` | | Enable Node.js version management. | | `nvm off` | | Disable version management (uninstalls nothing). | | `nvm proxy [url]` | | Set the download proxy; blank shows it; `none` removes it. | | `nvm node_mirror [url]` | | Set the Node download mirror. Blank resets to default. | | `nvm npm_mirror [url]` | | Set the npm download mirror. Blank resets to default. | | `nvm uninstall ` | `nvm rm` | Uninstall a specific version. | | `nvm reinstall ` | | Clean-remove and reinstall a version. | | `nvm use [version] [arch]` | `nvm u` | Switch the active version. Accepts `latest`/`lts`/`newest`, or just an arch. | | `nvm root [path]` | | Set or show the version storage root. | | `nvm upgrade` | | Update NVM for Windows itself to the latest release. | | `nvm subscribe [--]` | | Subscribe to desktop notifications (`lts`/`current`/`nvm4w`/`author`). | | `nvm unsubscribe [--]` | | Unsubscribe from desktop notifications. | | `nvm version` | `nvm v` | Display the installed NVM for Windows version. Also `--version`/`-v`. | > [!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 all`. Then switch architecture for the active version with `nvm use 32` or `nvm use 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 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](https://github.com/coreybutler/nvm-windows/releases) 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. --- _Generated June 2026 from coreybutler/nvm-windows at 5b18223. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._