How to switch Node.js versions with NVM

Editor’s note: This article was last reviewed and updated on 20 November 2024.

Have you ever wondered how to check the current, in-use Node version? To see what version is currently active, simply run node --version. This will execute the active Node and give you the version:

If you’re interested in learning to switch between different versions of Node.js, continue reading this guide, where we use Node Version Manager (NVM) to quickly install Node versions directly from the CLI and effortlessly switch between Node versions.

What is NVM?

Node Version Manager, or NVM, is a tool that helps manage Node versions and is a convenient way to install Node. Similar to how npm or Yarn help manage Node packages, NVM specializes in the management of Node.js versions, enhancing development flexibility and environment control.

This also means you can install multiple Node versions onto your machine at the same time and switch among them if needed.

Why Node.js developers need NVM

Developers who work with Node often encounter a scenario where they initially develop and host a project using Node version 12, only to find themselves needing to update a feature several months later on a machine running Node version 14.

You won’t be surprised that running npm install or yarn install to download the Node modules in this example displays errors regarding deprecated packages. There are also instances when you could use a higher version of Node when a project specifically requires an older version.

For instance, you might use an SPFx application or an SPFx solution that uses Node LTS v14, but you are simultaneously working on another Node application like cli-microsoft356, which works on a higher Node version.

In this case, you want to switch back and forth between different Node versions, and the easiest way to do this is by using Node Version Manager.

Every Node project also tends to have requirements for the version it supports. Personally, I have needed to contribute to a project that supports a Node version between 10.16 and 12 while my machine ran version 14 at the time.

Without NVM, I wouldn’t have been able to contribute to the project on the same machine without removing the existing version — risking significant disruptions — or resorting to dual booting, which can lower performance, particularly on older machines.

Since this article was originally written, Node version 20 has been released to the LTS branch. So, let’s set up NVM, but configure it to work with versions 12, 16, and 20 of Node.js.

Installing NVM

NVM can be installed and used to manage Node versions independently of any existing installations on your system. So, it isn’t necessary to have a Node version on your machine and if you already have one, it won’t impact NVM installation.

Executing nvm and node in the terminal reveals that both commands are unrecognized, displaying the messages Command nvm not found and Command node not found, respectively. It then provides guidance on how to install Node.js:

However, because we are not installing Node directly, we’ll focus on using NVM.

To install NVM, run the following command on your terminal:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

cURL comes with most Linux-based operating systems. If for any reason, you do not have cURL installed on your machine, you can download it from this guide. Running the above command downloads a script and runs it.

This script downloads the entire NVM repository to ~/.nvm and adds the source lines from the snippet below to the correct shell startup script, that is, ~/.bash_profile, ~/.zshrc, ~/.profile, or ~/.bashrc, depending on the shell program you are using.

In my case, I’m using ~/.bashrc:

//source line added
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # This loads nvm bash_completion

After that, exit the terminal and reopen it.

Run nvm and now you should see the following:

You have successfully installed NVM. Now, let’s install and manage multiple Node versions.

Installing and managing different Node.js versions

To install a Node version, simply run the following command:

nvm install --<the node version>

Let’s start by installing the latest LTS version, which is version 20.11.0 at the time of writing this article. This is done by running nvm install --lts, which produces the following screen:

We now have npm v10.2.4 as well. After this installs, it will automatically set the default Node version to the LTS that we just downloaded.

For this tutorial, we want three Node versions running on our machine. To find the list of available Node versions, run this:

nvm ls-remote

Running nvm install node installs the latest Node version available at the time. If we want to install v12.22.7, we simply run nvm install 12.22.7:

This downloads v12.22.7 from the source and installs it. At the time of using 12.22.7, the npm version is 6.14.15.

Whenever you download a new version, it replaces the previous one that was in use. Now let’s install version 14.18.1 with nvm install 14.18.1:

Displaying a list of Node.js versions

We can now view all the versions we downloaded so far; currently, we have three Node versions installed using NVM. To see the full list, run the following command:

nvm ls

The list then appears:

The first three lines show the list of Node versions with the arrow pointing to the 14.18.1 version that is currently in use; when a version is used, it displays as green.

If you happen to have more than three versions installed, of course, they will also display.

How to switch Node.js versions

The best feature of NVM is the ability to easily switch between different Node versions. Say we have to use v20.11.0 and then switch to 14.18.1; we can simply run either nvm use 20.11.70 or nvm use 14.18.1 to easily switch to either version we need:

Note that because we only have one version that begins with 12, 14, or 20, we can switch versions with a simple nvm use 20, nvm use 12, or nvm use 14 command:

Removing a Node.js version

Often, you may not need a particular version of Node for the projects you are working on. With NVM, you can easily remove the versions you don’t need.

To remove a version, just run the following command:

nvm uninstall <the version number>

The terminal will then show that the version is uninstalled:

You must note that each version of the installation is independent, meaning that global packages on the previous versions installed won’t be available on a new installation.

As for checking what version is currently active, we covered this in the introduction to this article. Simply run node --version, which will execute the active Node and give you the version.

To ensure that globally installed packages like Gatsby CLI are accessible after switching Node.js versions with NVM, it’s important to understand how NVM manages these packages. If you have the Gatsby CLI installed globally on version 14 of Node, for instance, when you switch to version 16 or any other version using NVM, the Gatsby CLI will not be available in the version you just switched to.

We can fix this by bringing all global packages to the new version of Node right when we first install it.

Again, know that NVM is Linux-based, meaning the installation sections and everything mentioned above will only work for Linux-based macOS or Linux-based distributions. If you’re a Windows user, check out this project by Corey Butler, which provides NVM for Windows. It is similar and it already has an installer here.

Troubleshooting the NVM install

Sometimes, despite following the instructions, nothing seems to work. This is complicated by the fact that we can be under some serious time pressure when we’re trying to get tools like NVM to work. Trying to install a legacy version of Node to fix a production issue with an older app is not a fun way to spend an afternoon.

Fortunately, it’s not so hard to troubleshoot, and hopefully resolve, problems that we may encounter with NVM. Let’s imagine we’ve just done the above, and we run nvm, and get the following result:

What happened? Our computer can’t find NVM. To double-check this, let’s run which nvm, which will produce the path to the nvm tool, if it exists on our local system:

No result. So our computer can’t find nvm in the currently set PATH variable.

Depending on your system, you’ll either have a .bashrc or .zshrc file responsible for setting the path for your shell when it starts up. To find out for sure, type echo $SHELL in your terminal:

So, we have a Bash shell. If you have zsh, it’ll have /bin/zsh instead. Either way, type cd ~ to navigate to our home directory. Once there:

• If you have a Bash shell, type nano .bashrc
• If you have a zsh shell, type nano .zshrc

Then, scroll down to the bottom of the file. In my case, it looks like this:

In my case, I temporarily disabled these lines to address a separate issue with my Bash shell but failed to comment them back in afterward. To correct this, I just need to remove the comment markers from these lines:

After saving this file, I can run source .bashrc, and then run nvm again to observe that nvm is now executable:

Persisting Node versions between shell sessions

Sometimes, you might be working on an older piece of software for a long time. Let’s imagine we have to work on something that uses Node 14.

We could write nvm use 14 in the terminal each time, but this will get old quickly. Plus, if we’re halfway through making changes, and we realize we’re using the wrong version, this could waste a lot of our time.

Fortunately, we can easily set a default version of Node that can be used each time the terminal starts up. To use Node 14 in our current session, and also use it in future sessions, we can type the following:

nvm use 14
nvm alias default 14

The result of this is that Node 14 is set as our active Node version:

And once we want to get back to the latest version of Node, we can use the following:

nvm use node
nvm alias default node

This will bring us back to version 20 of Node:

Conclusion

In this article, we explored Node Version Manager for managing multiple Node.js versions. NVM streamlines the process of installing, switching, and removing Node.js versions, enabling developers to efficiently manage different projects with varying Node.js requirements.

Through practical examples, we demonstrated how NVM addresses common versioning challenges, ensuring seamless development workflows. This tool is useful for developers seeking to maintain productivity and compatibility across diverse Node.js environments.