Common Issues
There are a couple of common issues folks run into. I try to fix them/accept PR's when possible, but some things need to be fixed by users.
Here are some common issues and workarounds:
NVM4W 1.1.11 introduces the nvm debug command. If NVM4W detects any problems, it will display them.
For example:
In the Node Collaborators Summit held in November 2024, nodejs.org switched its download server from an NGINX server to Cloudflare Workers. There was an undetected URL formatting bug in NVM for Windows (prior to version 1.2.0) causing an extra slash in the download URLs of older versions. The old NGINX system still resolved the path formatting issue, but the new Cloudflare worker did not. This caused download failures (see #1179). The nodejs.org team provided a temporary resolution so NVM for Widows users using old versions are not affected while they upgrade to 1.2.0 or higher. I've worked with the nodejs.org folks to keep this temporary fix in place until May 2025.
The Eager Beaver Problem:
When a new Node.js release is created on Github, two things happen. First, the build process is triggered. Second, notifications are broadcast. Essentially, a race condition is created because eager beavers want to download the new binaries the second they're announced... but the binaries aren't finished building for another 15-30 minutes after a release announcement.
Luckily, the resolution for this is simple... wait a few minutes and try again.
If the latest version has been released for awhile, check your proxies, firewalls, and antivirus tools to make sure nothing is being blocked.
Please note that we're building solutions for all of this in Runtime.
Hanging Downloads
Some users have reported very slow downloads when IPv6 is enabled. This is an operating system feature that NVM4W cannot control. The common rule of thumb is to disable IPv6 if it is causing your downloads to seemingly hang or download very slowly.
By popular demand, NVM4W 1.1.8 introduced support for developer mode. In other words, you won't receive a UAC prompt to elevate permissions if it's not explicitly necessary. If you prefer to be prompted for UAC rights, use NVM4W 1.1.7.
If you do not run the nvm.exe file with appropriate permissions, you may receive an exit 1, exit 5, or Access Denied error. These come straight from Windows, indicating the user account does not have permissions to do what you're trying to do.
The most common permission issue has to do with creating symlinks. NVM4W uses symlinks (mklink is used in nvm use) to redirect the Node installation path to the appropriate installation. Windows requires elevated administrative privileges to create symlinks, but developer mode eases these restrictions.
It's best to enable developer mode on Windows 10, which will grant your user account slightly elevated permissions. See how to Enable Your Device for Development
The second most common permission issue is trying to use a protected directory for storing Node installations. Windows requires administrative privileges to write to C:\Program Files. Many users want to install different versions of Node to this directory, but this forces NVM4W to create download (write) Node/npm to a protected directory. It's typically simpler to store Node installations in an alternative directory, such as C:\nvm4w, or on another drive such as d:\nodejs.
Several people have complained about protected directories, and I'm sorry... but I'm not the person to talk to about that. Your best bet is to reach out to Microsoft, because it's an operating system requirement. Every program has to deal with this. Remember that NVM4W is basically an installer, so it needs installer-like permissions.
The third most common permission issue is conflicting permissions. Many users fail to uninstall old versions of Node before installing NVM4W. The NVM for Windows installer attempts to migrate existing Node installations into NVM4W, but old installations can prevent this. The original Node installation is often installed with different user permissions, making it impossible for NVM4W to uninstall it. This results in two conflicting installations of Node. Node can physically exist in more than one location, but only one unscoped (i.e. globally available) version can be used at a time. This is why the README recommends uninstalling previous versions of Node before installing NVM4W.
The exit 145: The directory is not empty and exit 32: The process cannot access the file because it is being used by another process. errors are passed through from Windows itself. The errors are self-explanatory. Most users encounter one or the other because they're trying to change the Node.js version from within the directory of the Node installation. For example, if your root is C:\nvm4w and you install Node 16.9.1, it will be available at C:\nvm4w\v16.9.1. If you navigate to C:\nvm4w\v16.9.1 in the terminal/powershell or keep it open in Windows explorer, Windows will lock the directory (because it is open). If you try to run nvm use 16.11.0 (another version of Node), it will not be able to remove the original symlink, because it is locked. The easiest way to bypass this is to navigate to another directory (i.e. cd C:\ before running nvm use x.x.x).
An active Node process can also cause these problems. If an active process is running when attempting to nvm use a new version, it will fail. For example, if you run node mywebserver.js, a live process (using node.exe) is created. If you try to switch versions without shutting down the server, Windows will warn you the node.exe process is currently in use. It's kind of like saying "you can't uninstall this while you're still using it".
Some versions (particularly 1.1.8 and nvm-update.exe) are not code-signed. Some antivirus services use machine learning algorithms to determine threats on unsigned executables. If your antivirus recognizes a threat with a name like !ml, ML or .ML, it indicates a machine learning algorithm is making a guess about the application. These are not the same as known virus signatures. NVM4W has no malicious code, but version 1.1.8 is not code signed. See the release notes under the WARNING section for details.
After an undetermined number of installations, Microsoft Defender and Microsoft SmartScreen will trust the application. However; there is no way of knowing what that number is. You may need to make an exception in your antivirus for NVM4W.
If you cannot download a release, you may need to temporarily disable realtime protection. Always remember to turn this back on after your download completes!
Take note that running nvm-update.exe will download nvm-setup.zip, then extract all of the relevant files to update your installation and cleanup when done. You may need to temporarily disable Windows Defender realtime protection while doing this as well.
This issue should be resolved as of version 1.1.8.
If you are working with an older version...
Some environments aren't picking up on space-escaping. If you're having problems with Windows recognizing NVM4W, try installing it on a path with no spaces, like C:\nvm. The same situation is relevant for the symlink path, so you may want to use something other than C:\Program Files\nodejs for the symlink root.
If you're unsure whether you're impacted by this, try using the pathfinder troubleshooting utility.
The installer attempts to take over any existing installations of Node for you, but the process can be more complex than it appears. The most common source of problems is when users install NVM4W using a different account or with different permissions than those which are used to install prior versions. The bottom line is permissions for installing/uninstalling applications are quite strict and NVM4W may not be able to absorb prior installations.
The best course of action is to uninstall prior versions of Node before installing NVM4W. In some cases, you can uninstall prior versions afterwards, but the only reliable way I've consistently seen it work is by removing prior versions before installing NVM4W.
Depending on which version of Windows you have and how your desktop is setup, there can be issues with modifying a path in the registry for an application you don't control, user accounts associated with an existing app, roaming profiles, etc.
I only have a couple of versions of Windows to test on, but it's far from the complete Microsoft Windows catalog. Again, the one consistent solution that always seems to work is uninstalling Node before installing NVM4W.
When NVM for Windows is installed, it adds the NVM_SYMLINK to the PATH environment variable. The NVM_SYMLINK points to the directory where the operating system will look for the node.exe file. Windows scans the PATH entries, looking for node.exe, which it will find when it reaches the NVM_SYMLINK value. Here's an example of the PATH:
Windows scans each directory one-by-one until it finds node.exe, starting with C:\Users\corey\go\bin. It won't find node.exe there, so it moves on to C:\Users\corey\AppData\Local\GithubDesktop\bin and so on until it does find node.exe (in NVM_SYMLINK).
If Node.js is already installed before NVM4W is installed, there will be another directory containing Node.js before NVM_SYMLINK in the PATH. The result of this is anytime you run node myscript.js, it will find the previously installed version, not the version installed by NVM4W.
The NVM4W installer has an option which attempts to move the old Node.js version into a directory it can manage, but sometimes this is not possible. Sometimes Windows won't allow this because a different user added the original Node.js installation, or the current user doesn't have permissions to change the registry from the NVM4W installation process. Sometimes the only way to move/uninstall Node.js is using its dedicated uninstaller. This is why we recommend uninstalling Node.js before installing NVM4W.
Several users have reported issues installing versions of Node.js that ship with npm 6.14.7, such as Node 14.19.x (except 14.19.1, which uses npm 6.14.16). There has been an upstream problem with the npm download. Please see issue #799 for details.
Make sure you are using NVM for Windows 1.1.7 or greater. Older versions of NVM4W use the old npm github repository (which only has older versions).
Some users attempt to install old versions of npm for testing. Be aware that newer versions of npm won't necessarily work on older versions of Node.js. Older versions of npm won't necessarily work on newer versions of Node.js. NVM4W does not manage npm, it merely installs it. It is up to developers to assure the versions of Node/npm they're using are compatible.
Some users experience the following error:
npm ERR! path C:\Program Files\nodejs\npm.cmd npm ERR! code EEXIST npm ERR! Refusing to delete C:\Program Files\nodejs\npm.cmd: is outside C:\Program Files\nodejs\node_modules\npm and not a link npm ERR! File exists: C:\Program Files\nodejs\npm.cmd npm ERR! Move it away, and try again.
The best bet is to use this solution, https://github.com/felixrieseberg/npm-windows-upgrade
Some older versions of npm have hard coded paths that prevent automatic removal. Several users have found manual workarounds that work well.
Yarn is an npm package. npm install -g yarn will install it. Remember, yarn is not officially released with Node.js, so this will need to be repeated for each new installation of Node.js.
Per issue #417, some shells do not respect UAC prompts (i.e. requesting administrator permissions). NVM for Windows cannot control how terminals work, and due to the sheer number of custom terminals available (mingw, cmder, ConEmu, cygwin, hyper, etc), only official Windows terminals are supported (CMD and PowerShell). Bash for Windows support may come in the future.
If you are using a special terminal that does not respect UAC requests, you may see errors like this:
If Windows cannot find NVM, try restarting the terminal/powershell first. If the issue persists, it may be due to a misconfiguration in the terminal. See this stackoverflow answer for a possible fix.
Whenever nvm use x.x.x is called, NVM for Windows updates a symlink pointing to the x.x.x installation root. This can take a few milliseconds on the operating system, meaning the change is not immediately available. Some users have run into problems with this in CI environments with code like:
nvm use lts
npm i -g yarnIn some (not all) environments, the nvm use lts background process has not completed before the npm i -g yarn command is executed, causing it to fail. If you encounter this issue, add a slight delay:
nvm use lts
start-sleep -seconds 1
npm i -g yarnSometimes brand new installations aren't immediately available in the command prompt that launches after installing NVM for Windows. Unfortunately, a race condition can exist when the InnoSetup installer prepares to exit. In simple terms, Windows doesn't provide a way for InnoSetup to know when the PATH has been updated. The NVM4W script adds a simple delay in an attempt to give the operating system enough time to update the PATH before opening the prompt window. Unfortunately, this isn't exact and the timeframe isn't entirely predictable. Sometimes Windows lags behind the PATH update just long enough that it isn't complete when the terminal is opened, therefore the terminal loads an outdated PATH, making it seem like NVM4W isn't installed. Reopening the terminal will resolve this. This behavior is a result of using InnoSetup. Runtime (successor to NVM4W) will have an entirely different installer to resolve this problem once and for all.
One of the primary reasons we don't support .nvmrc is to minimize security vulnerabilities. See this discussion for an illustrative example of the vulnerabilities introduced by .nvmrc.
tldr; this feature will not be part of NVM4W (but will be part of Runtime). Some users have created workarounds:
The .nvmrc file is a concept that's a part of the nvm project. This project is and always has been different from the original nvm project. This project does not strive to be a mirror of the original nvm project.
The primary reason why .nvmrc files aren't supported is due to a key difference in the design philosophy. The nvm project uses a shim to access Node.js, whereas this project does not.
A shim is an executable/command that relays commands to another executable. Shims can reconstruct the command, which includes reading a config file (i.e. .nvmrc for a version, then constructing the command using the path to the nvmrc-specified version of Node.
Historically, shims cause edge cases on Windows systems. It is often deemed unreliable. The most common issue is failure to relay user and directory context directly to the other executable. For example, the current working directory of the shim is recognized instead of the Node executable, or the owner of the shim would differ from the user executing the script. It requires some scripts to be aware they're operating in the context of a shim instead of directly with Node.js. See the edge cases in the version management workgroup.
Shims are also a potential vulnerability point that some enterprises have struggled with. Shims are fundamentally a binary injection, i.e. a shim script can be easily altered to do things like send information to 3rd parties. Scripts cannot be code signed, which is one of the ways Windows confirms whether a file is changed or not. Checksums can be used to do this manually, but it's an extra step developers rarely take (and cybersecurity teams have difficulty enforcing).
The bottom line is calling a shim is not the same as calling node.exe.
NVM for Window's was designed to use Node.js executables directly. This is why symlinks are used instead of a shim. Philosophically, it aligns with how Node (or any runtime) is used without a version manager.
A note on the author's intentions:
Even though the name of this project is similar to an earlier project, they are not the same. I have no intention of adding .nvmrc support or mirroring nvm's every move (nor the other way around).
There has long been confusion around version management tools and what they're supposed to do. Attempts were made to align the goals of version management, but they ultimately fell flat, leading to no official standards. With the introduction of new JavaScript runtimes (like Deno) and cultures, I believe this effort transcends more than a single governance group.
The popularity of .nvmrc indicates there is a desire for more automated runtime/environment management. I feel this myself. However; the scope of this project has always been version management, not runtime or environment management. I've spent considerable time thinking about these concepts though. I believe runtime management is a valid community need/desire, but I also feel the .nvmrc concept only addresses a small part of it.
Instead of breaking the design scope of this project, I've chosen to work on a successor: Runtime. This was first announced at rt, described in "the future of this project" section. By harnessing the lessons learned from this project (which are plentiful), we're better equipped to build a better/unified overall solution for all users (not just Windows users).
NVM4W is not designed to manage more than one version of Node.js at the same time, but it is still possible to run more than one version at the same time. If you need to run more than one version of Node at the same time, use the absolute path of the version you want. For example, if your NVM4W installation looks like this:
It is possible to run a script directly, like this:
In other words, run C:\path\to\version\node.exe myscript.js instead of just node myscript.js.
The same is possible with npm:
You can even run npm commands this way. For example, your package.json could look like this:
{
"name": "tmp",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1",
"dev": "echo \"running script from package.json...\""
},
"author": "",
"license": "ISC",
"dependencies": {
"porthog": "^1.0.1"
}
}Running the dev command would look like this:
After a new installation, if npm is not recognized, it is usually attributed to one of the following reasons:
- Node wasn't installed (i.e.
nvm install <version>). - The user account used to install Node did not have permissions to install it properly (see permissions).
- The user did not remove an old Node.js installation before installing NVM for Windows.
- A proxy or bad network connection prevented the download of npm.
- The user tried to install a version of Node with an unsupported shell, such as Cygwin.
Yes, I know how much easier some people's lives would be with junctions. However; a very conservative estimate of 40% of the NVM for Windows users are enterprise users. In this scenario, it is common for users to have their programs on mapped directories/SAN/NAS drives. Junctions don't work on these. NVM for Windows has about 11M users as of this writing. There's absolutely no way I'm going to introduce a feature that can break it for over 4M people.
I have considered making junctions an option, allowing people to toggle this on/off, but I don't have time to introduce that. There will be tons of users needing help moving to junctions. Besides, NVM for Windows will be replaced by Runtime in the very near future. Runtime will use a smart shim instead of symlinks, so this won't be a problem anymore.
The most common reason for this failure is a missing/invalid symlink. If you run nvm debug, it will tell you if this is the problem.
Reasons for invalid symlinks:
- The user account doesn't have permission to create symlinks.
- The path specified for the symlink already exists. For example, if you try to specify
C:\Program Files\nodejsand that folder already exists, it will fail. A symlink cannot overwrite a real directory/file. - Missing
NVM_SYMLINKenvironment variable.
To resolve this problem, set your NVM_SYMLINK environment variable to a path that does not conflict with an existing one. For example, setting the symlink to C:\PATH\TO\nodejs will work as long as C:\PATH\TO exists and nodejs does not.