A guide to NVM: managing Node.js versions with ease

Node Version Manager (NVM) is a powerful command line utility that makes it easy to manage Node.js versions on your system. This is particularly useful when you're working on projects that may have specific Node.js version requirements. With NVM, you can install multiple versions of Node.js side by side and switch between them effortlessly.

You can mark the version you need for your project in the .nvmrc config file in the project's root, in order to avoid problems in the team in the future like: “this project won’t run on the latest version of the engine.”

NVM is a command line utility available on Linux, macOS and Windows.

Installing NVM

Linux or macOS

To install NVM on Linux or macOS, you can use the following curl or wget command:

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

wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

If the installer does not find a profile for your terminal shell, you will see an error:

=> Profile not found. Tried ~/.bashrc, ~/.bash_profile, ~/.zprofile, ~/.zshrc, and ~/.profile.
=> Create one of them and run this script again

After the installation is complete, restart your terminal to start using NVM.

Windows

On Windows, you can use the installer provided by the NVM for Windows project. Visit the project's GitHub page and download the latest installer. Run the installer and follow the on-screen instructions.

Using NVM

Installing Node.js Versions

Now that NVM is installed, you can easily install Node.js versions. To install a specific version, use the following command:

nvm install <version>

For example, to install Node.js version 16, you would run:

nvm install 16

Switching Between Node.js Versions

To switch between installed Node.js versions, use the use command:

nvm use 16

Default Node.js Version

You can set a default Node.js version that NVM will use when opening a new terminal window:

nvm alias default <version>

Listing Installed Node.js Versions

To list all installed Node.js versions, use:

nvm ls

Auto-Switching Node.js Versions with NVM

One of the powerful features of NVM is the ability to automatically switch Node.js versions based on the directory you are in. This is particularly useful when working on projects with different Node.js requirements.

To mark fixed Node.js version for your project, you need to create a .nvmrc file in your project's root directory. In this file, specify the desired version. For example:

echo "20.5" > .nvmrc

Or lock current version:

echo "$(node -v)" > .nvmrc

To enable auto-switching by entering directory in terminal, we heed to add a command to shell profile. Select the desired snippet from the documentation. And restart the shell.

My zsh shell the profile file for example.

## Settings from nvm installer
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

## Auto-switching node.js versions
# place this after nvm initialization!
autoload -U add-zsh-hook
load-nvmrc() {
  local node_version="$(nvm version)"
  local nvmrc_path="$(nvm_find_nvmrc)"

  if [ -n "$nvmrc_path" ]; then
    local nvmrc_node_version=$(nvm version "$(cat "${nvmrc_path}")")

    if [ "$nvmrc_node_version" = "N/A" ]; then
      nvm install
    elif [ "$nvmrc_node_version" != "$node_version" ]; then
      nvm use
    fi
  elif [ "$node_version" != "$(nvm version default)" ]; then
    echo "Reverting to nvm default version"
    nvm use default
  fi
}
add-zsh-hook chpwd load-nvmrc
load-nvmrc

From now with the .nvmrc file in place, whenever you navigate to the project directory using the terminal, NVM will automatically switch to the specified Node.js version. Even if the target version is not dowloaded to your computer, NVM will gently install and use it.

% cd my-project
Found '/Volumes/Dev/my-project/.nvmrc' with version <20.5.1>
Downloading and installing node v20.5.1...
Downloading https://nodejs.org/dist/v20.5.1/node-v20.5.1-darwin-x64.tar.xz...
######################################################################### 100.0%
Computing checksum with shasum -a 256
Checksums matched!
Now using node v20.5.1 (npm v9.8.0)

% node -v
v20.5.1

Also in different terminal windows you may use different node versions for projects. How cool is that.

Conclusion

NVM is a versatile tool that simplifies Node.js version management. Whether you need to switch between Node.js versions manually or set up automatic version switching for different projects.

Please, don't be shy to lock the engine version for your project. It will save your time in the future.