Why version management matters

Imagine you maintain two projects: a legacy APIWhat is api?A set of rules that lets one program talk to another, usually over the internet, by sending requests and getting responses. Ask AI for more locked to Node 16, and a new service taking advantage of features introduced in Node 20. Without a version manager you are constantly uninstalling and reinstalling Node.js, or worse, running the wrong version and debugging mysterious incompatibility errors.

NVMWhat is nvm?Node Version Manager - a tool that lets you install multiple Node.js versions and switch between them per project. Ask AI for more keeps every version you install in its own isolated directory. Switching is a single command.

Installing NVMWhat is nvm?Node Version Manager - a tool that lets you install multiple Node.js versions and switch between them per project. Ask AI for more

macOS and Linux

Run the official install script, which downloads NVM and adds it to your shell profile:

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

After the script runs, either open a new terminalWhat is terminal?A text-based interface where you type commands to interact with your computer. Also called the command line or shell. Ask AI for more window or source your shell profile manually:

# For bash
source ~/.bashrc

# For zsh (default on modern macOS)
source ~/.zshrc

Verify the installation worked:

nvm --version
# 0.39.0

Windows

NVM itself is macOS/Linux only. On Windows, use nvm-windows: a separate project with the same core concept: httpsWhat is https?HTTP with encryption added, so data traveling between your browser and a server can't be read or tampered with by anyone in between. Ask AI for more://github.com/coreybutler/nvm-windows. The commands are nearly identical.

Core NVMWhat is nvm?Node Version Manager - a tool that lets you install multiple Node.js versions and switch between them per project. Ask AI for more commands

Once NVM is installed, these are the commands you will use every day:

# List all available versions (use grep to filter)
nvm ls-remote
nvm ls-remote --lts          # LTS versions only

# Install a version
nvm install 20               # Installs latest 20.x.x
nvm install 18.17.0          # Installs an exact version

# Switch to a version in the current shell session
nvm use 20

# Set the default version for all new terminals
nvm alias default 20

# See which versions you have installed
nvm ls

# Remove an installed version
nvm uninstall 16

Verifying your installation

After installing and selecting a version, confirm that both node and npm are on your PATH:

node --version
# v20.10.0

npm --version
# 10.2.3

You can also launch the interactive REPLWhat is repl?Read-Eval-Print Loop - an interactive prompt where you type code and see the result immediately, like running node with no arguments. Ask AI for more (Read-Eval-Print Loop) to run Node.js code directly in your terminalWhat is terminal?A text-based interface where you type commands to interact with your computer. Also called the command line or shell. Ask AI for more, useful for quick experiments:

node
> console.log('Hello from Node.js')
Hello from Node.js
undefined
> 2 + 2
4
> .exit

Locking a version per project with .nvmrc

The .nvmrc file is a small text file at the root of your project containing a single version number. When you (or a teammate) run nvm use in that directory, NVMWhat is nvm?Node Version Manager - a tool that lets you install multiple Node.js versions and switch between them per project. Ask AI for more reads the file and switches to the specified version automatically.

# Create the file
echo "20" > .nvmrc

# Later, anyone can run this in the project root
nvm use
# Found '/path/to/project/.nvmrc' with version <20>
# Now using node v20.10.0

Always commitWhat is commit?A permanent snapshot of your staged changes saved in Git's history, identified by a unique hash and accompanied by a message describing what changed. Ask AI for more .nvmrc to version control. It is a zero-cost way to prevent "works on my machine" version mismatches.

LTSWhat is lts?Long Term Support - a release track that receives security and bug-fix updates for an extended period, recommended for production. Ask AI for more versus current releases

Node.js releases two kinds of versions:

LTS versions receive security patches and bug fixes for 30 months after release. Current versions are supported for only six months before being dropped. For any production workload, always use an LTS version.

Troubleshooting common problems

"nvmWhat is nvm?Node Version Manager - a tool that lets you install multiple Node.js versions and switch between them per project. Ask AI for more: command not found" after installation

The install script adds initialization code to your shell profile, but if you use a non-standard shell setup the lines may land in the wrong file. Add them manually:

# Add these lines to ~/.zshrc or ~/.bashrc
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

Then run source ~/.zshrc (or restart your terminalWhat is terminal?A text-based interface where you type commands to interact with your computer. Also called the command line or shell. Ask AI for more).

Permission errors when installing packages

You should never need sudo to install npm packages. If you see permission errors, it usually means Node.js was installed outside NVM (perhaps via brew install node or the official installer) and left behind files owned by root.

Fix it by pointing npm's global prefix to a directory you own:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH="$HOME/.npm-global/bin:$PATH"

Add the export line to your shell profile so it persists across sessions.

Quick reference