How To Use NVM To Manage Node.js 21 and NPM 10

A practical guide for NVM

Node.js 21 was released on October 17, 2023. It comes with npm 10 and many new features. Are you ready to try it out?

As we stated in the previous article, NVM (Node Version Manager) is the best way to upgrade node.js and npm versions. It can help us to mitigate the risk.

This is a rewrite with new versions of nvm, node.js, and npm.

Install NVM

nvm manages node.js and npm versions. It is designed to be installed per user and invoked per shell. nvm works on any POSIX-compliant shell (sh, dash, ksh, zsh, bash), particularly on Unix, macOS, and windows WSL.

The latest version of nvm is 0.39.5, and it can be installed by curl or wget command:

% curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash
% wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash

The script, install.sh, clones the nvm repository to ~/.nvm, and attempts to add the source lines from the snippet below to the correct profile file (~/.bash_profile, ~/.zshrc, ~/.profile, or ~/.bashrc).

Run the curl command:

% curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 15916  100 15916    0     0  45716      0 --:--:-- --:--:-- --:--:-- 46674
=> nvm is already installed in /Users/jenniferfu/.nvm, trying to update using git
=> => Compressing and cleaning up git repository

=> nvm source string already in /Users/jenniferfu/.zshrc
=> bash_completion source string already in /Users/jenniferfu/.zshrc
=> Close and reopen your terminal to start using nvm or run the following to use it now:

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

In the profile file, such as ~/.zshrc, we see the following lines are added:

export NVM_DIR=/Users/jenniferfu/.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

Execute the profile file, and nvm is ready to be used.

% source ~/.zshrc
% nvm -v
0.39.5

The above step works for upgrade as well.

Use NVM

After nvm is installed, we can use the following command to install the latest version of node.js:

% nvm install node
Downloading and installing node v21.0.0...
Downloading https://nodejs.org/dist/v21.0.0/node-v21.0.0-darwin-x64.tar.xz...
###################################################################### 100.0%
Computing checksum with sha256sum
Checksums matched!
Now using node v21.0.0 (npm v10.2.0)

The above output states that npm 10.2.0 is used along with node.js 21.0.0. This can be verified with the following commands:

% node -v
v21.0.0
% npm -v
10.2.0

We can also use nvm to specify the exact version to be installed. The semantic version format is defined by SemVer:

% nvm install 20.2.0
Downloading and installing node v20.2.0...
Downloading https://nodejs.org/dist/v20.2.0/node-v20.2.0-darwin-x64.tar.xz...
############################################################################################### 100.0%
Computing checksum with sha256sum
Checksums matched!
Now using node v20.2.0 (npm v9.6.6)

If the specific version has already been installed, it will not be reinstalled:

% nvm install 20.2.0
v20.2.0 is already installed.
Now using node v20.2.0 (npm v9.6.6)

Want to change npm to version 9.0.0?

% npm install -g npm@9.0.0

removed 46 packages, and changed 86 packages in 2s

14 packages are looking for funding
  run `npm fund` for details

But, there are restrictions on versions:

% npm install -g [email protected]
npm ERR! code EBADENGINE
npm ERR! engine Unsupported engine
npm ERR! engine Not compatible with your version of node/npm: [email protected]
npm ERR! notsup Not compatible with your version of node/npm: [email protected]
npm ERR! notsup Required: {"node":"^18.17.0 || >=20.5.0"}
npm ERR! notsup Actual:   {"npm":"9.0.0"}

npm ERR! A complete log of this run can be found in:
npm ERR!     /Users/jenniferfu/.npm/_logs/2023-10-24T05_11_50_383Z-debug-0.log

We can list all installed versions:

% nvm install 20.2.0
v20.2.0 is already installed.
Now using node v20.2.0 (npm v9.0.0)
jenniferfu@jenniferfu domino % nvm ls
       v0.11.16
       v10.14.0
       v12.22.7
       v14.17.6
       v14.20.1
        v16.0.0
       v16.13.2
       v16.19.0
       v16.19.1
       v16.20.0
        v17.0.0
        v17.1.0
        v17.3.0
        v18.0.0
        v19.0.0
        v20.0.0
->      v20.2.0
        v21.0.0
         system
default -> 16.20.0 (-> v16.20.0)
iojs -> N/A (default)
node -> stable (-> v21.0.0) (default)
stable -> 21.0 (-> v21.0.0) (default)
unstable -> 0.11 (-> v0.11.16) (default)
lts/* -> lts/hydrogen (-> N/A)
lts/argon -> v4.9.1 (-> N/A)
lts/boron -> v6.17.1 (-> N/A)
lts/carbon -> v8.17.0 (-> N/A)
lts/dubnium -> v10.24.1 (-> N/A)
lts/erbium -> v12.22.12 (-> N/A)
lts/fermium -> v14.21.3 (-> N/A)
lts/gallium -> v16.20.2 (-> N/A)
lts/hydrogen -> v18.18.2 (-> N/A)

The arrow in the above output shows that the current version of node.js is 20.2.0.
default is set to 16.20.0.
io.js, a fork of node.js, is not set.
node, i.e. stable node, is set to 21.0.0.
stable node is set to 21.0.0.
unstable node is set to 0.11.16, which has been obsoleted.

nvm use changes the current version:

% nvm use 12.22.7
Now using node v12.22.7 (npm v8.19.2)
% nvm use 14
Now using node v14.20.1 (npm v9.0.1)
% nvm use 17.1
Now using node v17.1.0 (npm v8.1.2)
% nvm use 19.0.0
Now using node v19.0.0 (npm v9.0.1)
% nvm use 20.0.0
Now using node v20.0.0 (npm v9.6.4)
% nvm use 21.0.0
Now using node v21.0.0 (npm v10.2.0)
% nvm use default
Now using node v16.20.0 (npm v9.6.4)
% nvm use node
Now using node v21.0.0 (npm v10.2.0)
% nvm use unstable
Now using node v0.11.16 (npm v2.3.0)
% nvm use stable
Now using node v21.0.0 (npm v10.2.0)
% nvm use iojs
N/A: version "iojs" is not yet installed.

You need to run `nvm install iojs` to install and use it.
% nvm use xyz
N/A: version "xyz" is not yet installed.

You need to run `nvm install xyz` to install and use it.

You may wonder how v14.20.1 uses a later version of npm (v9.0.1) than v17.1.0’s npm (v8.1.2). The following commands can achieve this:

% nvm use 14.20.1
% npm install -g npm@9.0.1

The following command will get the latest supported npm version on the current node version:

% nvm install-latest-npm
Attempting to upgrade to the latest working version of npm...
* Installing latest `npm`; if this does not work on your node version, please report a bug!

changed 31 packages in 2s

29 packages are looking for funding
  run `npm fund` for details
* npm upgraded to: v10.2.1

For node.js 21.0.0, the latest working version of npm is 10.2.1.

nvm use sets a specific version for the current shell. The newly set node.js version will be lost if you start a new shell.

How can we make a specific node version persistent?

The default version is the one that carries over to all shells. nvm alias can set the default version.

%  nvm alias default 16
default -> 16 (-> v16.20.0)

A .nvmrc file can be created for convenience, which takes SemVer format, or node, or default. Afterward, nvm use, nvm install, nvm exec, nvm run, and nvm which will use the version specified in the .nvmrc file if no version is supplied on the command line.

% cat .nvmrc
21.0.0
% nvm use
Found '/Users/jenniferfu/.nvmrc' with version <21.0.0>
Now using node v21.0.0 (npm v10.2.1)

We can check the current version with the following command:

% nvm current
v21.0.0

ls-remote lists all available versions, but be prepared for a very long list.

% nvm ls-remote

More specifically, providing a partial version can narrow down the available list.

% nvm ls-remote 21
->      v21.0.0
% nvm ls-remote 20
        v20.0.0
        v20.1.0
        v20.2.0
        v20.3.0
        v20.3.1
        v20.4.0
        v20.5.0
        v20.5.1
        v20.6.0
        v20.6.1
        v20.7.0
        v20.8.0
        v20.8.1

nvm which shows the path to the executable to where it was installed. We have installed node.js of 12.22.7, 14.17.6, 16.19.1, 17.3.0, 18.0.0, 19.0.0, 20.0.0, and 21.0.0. Here are the nvm which results:

% nvm which 12.22.7
/Users/jenniferfu/.nvm/versions/node/v12.22.7/bin/node
% nvm which 14.17.6
/Users/jenniferfu/.nvm/versions/node/v14.17.6/bin/node
% nvm which 16.19.1
/Users/jenniferfu/.nvm/versions/node/v16.19.1/bin/node
% nvm which 17.3.0
/Users/jenniferfu/.nvm/versions/node/v17.3.0/bin/node
% nvm which 18.0.0
/Users/jenniferfu/.nvm/versions/node/v18.0.0/bin/node
% nvm which 19.0.0
/Users/jenniferfu/.nvm/versions/node/v19.0.0/bin/node
% nvm which 20.0.0
/Users/jenniferfu/.nvm/versions/node/v20.0.0/bin/node
% nvm which 21.0.0
/Users/jenniferfu/.nvm/versions/node/v21.0.0/bin/node

A specific node version can be used directly to run an app:

% nvm run 18.0.0 app.js

Alternatively, the following command runs node app.js with the PATH pointing to node 20.0.0.

% nvm exec 20.0.0 node app.js

If you want to find more details about nvm, run the help command:

% nvm --help

Node Version Manager (v0.39.5)

Note: <version> refers to any version-like string nvm understands. This includes:
  - full or partial version numbers, starting with an optional "v" (0.10, v0.1.2, v1)
  - default (built-in) aliases: node, stable, unstable, iojs, system
  - custom aliases you define with `nvm alias foo`

 Any options that produce colorized output should respect the `--no-colors` option.

Usage:
  nvm --help                                  Show this message
    --no-colors                               Suppress colored output
  nvm --version                               Print out the installed version of nvm
  nvm install [<version>]                     Download and install a <version>. Uses .nvmrc if available and version is omitted.
   The following optional arguments, if provided, must appear directly after `nvm install`:
    -s                                        Skip binary download, install from source only.
    -b                                        Skip source download, install from binary only.
    --reinstall-packages-from=<version>       When installing, reinstall packages installed in <node|iojs|node version number>
    --lts                                     When installing, only select from LTS (long-term support) versions
    --lts=<LTS name>                          When installing, only select from versions for a specific LTS line
    --skip-default-packages                   When installing, skip the default-packages file if it exists
    --latest-npm                              After installing, attempt to upgrade to the latest working npm on the given node version
    --no-progress                             Disable the progress bar on any downloads
    --alias=<name>                            After installing, set the alias specified to the version specified. (same as: nvm alias <name> <version>)
    --default                                 After installing, set default alias to the version specified. (same as: nvm alias default <version>)
  nvm uninstall <version>                     Uninstall a version
  nvm uninstall --lts                         Uninstall using automatic LTS (long-term support) alias `lts/*`, if available.
  nvm uninstall --lts=<LTS name>              Uninstall using automatic alias for provided LTS line, if available.
  nvm use [<version>]                         Modify PATH to use <version>. Uses .nvmrc if available and version is omitted.
   The following optional arguments, if provided, must appear directly after `nvm use`:
    --silent                                  Silences stdout/stderr output
    --lts                                     Uses automatic LTS (long-term support) alias `lts/*`, if available.
    --lts=<LTS name>                          Uses automatic alias for provided LTS line, if available.
  nvm exec [<version>] [<command>]            Run <command> on <version>. Uses .nvmrc if available and version is omitted.
   The following optional arguments, if provided, must appear directly after `nvm exec`:
    --silent                                  Silences stdout/stderr output
    --lts                                     Uses automatic LTS (long-term support) alias `lts/*`, if available.
    --lts=<LTS name>                          Uses automatic alias for provided LTS line, if available.
  nvm run [<version>] [<args>]                Run `node` on <version> with <args> as arguments. Uses .nvmrc if available and version is omitted.
   The following optional arguments, if provided, must appear directly after `nvm run`:
    --silent                                  Silences stdout/stderr output
    --lts                                     Uses automatic LTS (long-term support) alias `lts/*`, if available.
    --lts=<LTS name>                          Uses automatic alias for provided LTS line, if available.
  nvm current                                 Display currently activated version of Node
  nvm ls [<version>]                          List installed versions, matching a given <version> if provided
    --no-colors                               Suppress colored output
    --no-alias                                Suppress `nvm alias` output
  nvm ls-remote [<version>]                   List remote versions available for install, matching a given <version> if provided
    --lts                                     When listing, only show LTS (long-term support) versions
    --lts=<LTS name>                          When listing, only show versions for a specific LTS line
    --no-colors                               Suppress colored output
  nvm version <version>                       Resolve the given description to a single local version
  nvm version-remote <version>                Resolve the given description to a single remote version
    --lts                                     When listing, only select from LTS (long-term support) versions
    --lts=<LTS name>                          When listing, only select from versions for a specific LTS line
  nvm deactivate                              Undo effects of `nvm` on current shell
    --silent                                  Silences stdout/stderr output
  nvm alias [<pattern>]                       Show all aliases beginning with <pattern>
    --no-colors                               Suppress colored output
  nvm alias <name> <version>                  Set an alias named <name> pointing to <version>
  nvm unalias <name>                          Deletes the alias named <name>
  nvm install-latest-npm                      Attempt to upgrade to the latest working `npm` on the current node version
  nvm reinstall-packages <version>            Reinstall global `npm` packages contained in <version> to current version
  nvm unload                                  Unload `nvm` from shell
  nvm which [current | <version>]             Display path to installed node version. Uses .nvmrc if available and version is omitted.
    --silent                                  Silences stdout/stderr output when a version is omitted
  nvm cache dir                               Display path to the cache directory for nvm
  nvm cache clear                             Empty cache directory for nvm
  nvm set-colors [<color codes>]              Set five text colors using format "yMeBg". Available when supported.
                                               Initial colors are:
                                                  bygre
                                               Color codes:
                                                r/R = red / bold red
                                                g/G = green / bold green
                                                b/B = blue / bold blue
                                                c/C = cyan / bold cyan
                                                m/M = magenta / bold magenta
                                                y/Y = yellow / bold yellow
                                                k/K = black / bold black
                                                e/W = light grey / white
Example:
  nvm install 8.0.0                     Install a specific version number
  nvm use 8.0                           Use the latest available 8.0.x release
  nvm run 6.10.3 app.js                 Run app.js using node 6.10.3
  nvm exec 4.8.3 node app.js            Run `node app.js` with the PATH pointing to node 4.8.3
  nvm alias default 8.1.0               Set default node version on a shell
  nvm alias default node                Always default to the latest available node version on a shell

  nvm install node                      Install the latest available version
  nvm use node                          Use the latest version
  nvm install --lts                     Install the latest LTS version
  nvm use --lts                         Use the latest LTS version

  nvm set-colors cgYmW                  Set text colors to cyan, green, bold yellow, magenta, and white

Note:
  to remove, delete, or uninstall nvm - just remove the `$NVM_DIR` folder (usually `~/.nvm`)

Conclusion

nvm makes it easy to manage node.js and npm versions. We can upgrade to node.js 21 and npm 10, or any other versions.

Thanks for reading.

Want to Connect?

If you are interested, check out my directory of web development articles.

In Plain English

Thank you for being a part of our community! Before you go:

Be sure to clap and follow the writer! 👏
You can find even more content at PlainEnglish.io 🚀
Sign up for our free weekly newsletter. 🗞️
Follow us: Twitter(X), LinkedIn, YouTube, Discord.
Check out our other platforms: Stackademic, CoFeed, Venture.