Switching Node Versions with NVM

Basic Usage

NVM provides simple yet powerful commands to switch between different Node.js versions. The most basic command is nvm use, which allows you to activate an installed Node.js version.

Viewing Available Node Versions

Before switching, you can use the nvm ls command to see what Node.js versions are installed.

nvm ls

Different Ways to Switch Versions

Using Full Version Numbers

You can specify the complete version number:

For example, to use Node.js v24.0.2:

$ nvm use 24.0.2
Now using node v24.0.2 (64-bit)

Using Major Version Numbers

Just specify the major version number, and NVM will use the latest installed version of that major version:

$ nvm use 14
Using node v14.17.6 (npm v6.14.15)

Using Aliases

NVM has several built-in special aliases:

# Use latest stable version
$ nvm use node
Now using node v16.14.0 (npm v8.3.1)

# Use latest LTS version
$ nvm use lts/*
Now using node v16.13.2 (npm v8.1.2)

# Use specific LTS version
$ nvm use lts/gallium
Now using node v16.13.2 (npm v8.1.2)

Specifying Architecture (Windows Only)

On Windows systems, you can specify whether to use the 32-bit or 64-bit version:

$ nvm use 14.17.0 32
$ nvm use 16.14.0 64

Automatic Version Switching with .nvmrc Files

Create a file named .nvmrc in your project's root directory with the Node.js version number as its content. Then, simply run the nvm use command (without arguments), and NVM will read the version from the .nvmrc file and switch to that version automatically.

1. Create an .nvmrc file:

$ echo "16.14.0" > .nvmrc

2. Run in the project directory:

$ nvm use
Found '/path/to/project/.nvmrc' with version <16.14.0>
Now using node v16.14.0 (npm v8.3.1)

Examples of .nvmrc file contents:

• 16.14.0 - Exact version
• 16 - Latest version of the major version
• lts/* - Latest LTS version
• node - Latest Node.js version

Setting a Default Node.js Version

You can set a default Node.js version that will be automatically used each time you open a new terminal:

$ nvm alias default 16.14.0
default -> 16.14.0 (-> v16.14.0)

This way, even if you don't run the nvm use command, the specified version will be used by default.

Considerations When Switching Versions

Global Package Management

When switching Node.js versions, globally installed packages don't automatically migrate. Each Node.js version has its own separate set of global packages.

If you want to copy all global packages from one version to another, you can use:

# Copy global packages from v14.17.0 to v16.14.0
$ nvm install 16.14.0 --reinstall-packages-from=14.17.0

Temporarily Using Another Version

If you just want to run a command with a different Node.js version without switching the current session's version, you can use nvm run:

$ nvm run 14.17.0 app.js

Checking the Current Version

To check which Node.js version is currently being used:

$ nvm current
v16.14.0

Common Issues and Solutions

Environment Variables Lost After Switching

Issue: After switching versions, previously set environment variables like NODE_PATH may be lost. Solution: Add environment variable settings to your .bashrc or .zshrc file.

Automatic Version Switching

If you want to automatically switch to the Node.js version specified in the .nvmrc file when entering a project directory, you can add the following to your .bashrc or .zshrc:

For Bash:

cdnvm() {
    command cd "$@" || return $?
    nvm_path="$(nvm_find_up .nvmrc | tr -d '\n')"
    
    if [ -e "$nvm_path/.nvmrc" ]; then
        declare default_version;
        default_version="$(nvm version default)"
        
        declare nvmrc_version;
        nvmrc_version="$(nvm version "$(cat "$nvm_path/.nvmrc")")"
        
        if [ "$nvmrc_version" = "N/A" ]; then
            echo "Warning: $(cat "$nvm_path/.nvmrc") version not installed"
        elif [ "$nvmrc_version" != "$default_version" ]; then
            nvm use > /dev/null
        fi
    fi
}
alias cd='cdnvm'

For Zsh:

autoload -U add-zsh-hook
load-nvmrc() {
  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" != "$(nvm version)" ]; then
      nvm use
    fi
  elif [ -n "$(PWD=$OLDPWD nvm_find_nvmrc)" ] && [ "$(nvm version)" != "$(nvm version default)" ]; then
    echo "Reverting to nvm default version"
    nvm use default
  fi
}
add-zsh-hook chpwd load-nvmrc
load-nvmrc

Best Practices

1. Create an .nvmrc file for each project: Ensures team members use the same Node.js version
2. Regularly update to LTS versions: LTS versions are more stable and suitable for production environments
3. Use semantic versioning: Specify exact versions in .nvmrc files to avoid compatibility issues
4. Set an appropriate default version: Set a default Node.js version for everyday development

nvm use Command Parameters

Parameter	Description
<version>	Specifies the Node.js version to use
node	Uses the latest version of Node.js
lts/*	Uses the latest long-term support version
lts/<name>	Uses a specific long-term support version
<version> <architecture>	(Windows only) Specifies whether to use 32 or 64-bit version

With these methods, you can easily switch between different Node.js versions to meet the development needs of different projects.