Quick Guide: Installing and Automating Node.js Versions with nvm

nvm-sh/nvm

Here's a friendly, detailed explanation of how it can help you, along with installation steps and code examples.

As engineers, we often work on multiple projects simultaneously. These projects rarely use the exact same tool versions, and this is where nvm shines.

Different projects may require different major, minor, or patch versions of Node.js.

The Problem
Your legacy project might only work reliably on Node 14, but your new project needs the latest features in Node 20. Without nvm, constantly switching and managing these versions manually is a nightmare.

The Solution
nvm allows you to define and switch the active Node.js version per terminal session or per project directory. It ensures you always run the correct version for the task at hand.

When updating a dependency or preparing for a Node.js major release, you need to verify compatibility.

The Benefit
You can quickly install and switch to different Node.js versions (e.g., jump from Node 18 to Node 20) to run your test suite against them. This dramatically speeds up testing and migration efforts.

nvm manages Node.js and its associated npm (Node Package Manager) and global packages independently for each installed version.

The Outcome
Global packages (like TypeScript or utility CLIs) installed under Node 14 won't clutter or conflict with packages installed under Node 20. This keeps your environment clean and avoids version conflicts.

Since nvm is a POSIX-compliant shell script, installation is straightforward, typically involving a single command.

You can install nvm using either curl or wget. It's generally recommended to check the official nvm-sh/nvm GitHub repository for the absolute latest installation command, but here is the common approach

# 1. Use curl to download and run the install script. 
#    Replace '0.39.7' with the latest version number if necessary.
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

What this does

It downloads the install.sh script.

It creates the ~/.nvm directory.

It attempts to add the necessary loading code to your shell's profile file (e.g., ~/.bashrc, ~/.zshrc, or ~/.profile).

After running the script, you'll need to close and reopen your terminal, or manually source your profile file (source ~/.bashrc) for nvm to become available.

Once installed, here are the most crucial commands you'll use daily

Imagine you have two projects
Project Alpha (legacy) and Project Beta (new).

First, make sure both versions are installed on your system

# Install Node 16 (LTS Gallium)
nvm install 16 

# Install Node 20 (LTS Iron)
nvm install 20 

# Check the list to confirm installation
nvm list 

Output of nvm list might look something like this

->     v20.10.0  # Currently active
       v16.20.2
default -> 20 (-> v20.10.0)

Navigate to the project directory and switch the version

cd ~/projects/alpha

# Switch to Node 16 for this session
nvm use 16 

# Run your project (it will now use Node 16's binary)
npm start 

Open a new terminal window (or simply switch versions) to work on Project Beta

cd ~/projects/beta

# Switch to Node 20 for this session
nvm use 20 

# Run your project (it will now use Node 20's binary)
npm run dev 

Pro Tip
Automating the Switch

To avoid manually typing nvm use <version>, you can create a file named .nvmrc in your project's root directory containing only the version number (e.g., 16.20.2 or simply 16).

Then, when you navigate to the directory, you can simply run

# In the project directory with a .nvmrc file
nvm use 
# nvm automatically detects the version from .nvmrc and switches!