nvm

What it is

nvm is a version manager for Node.js. It is a shell script that you install per user and run per shell, so each terminal can use a different Node.js version without touching a system copy. The README says it works on any POSIX-compliant shell (sh, dash, ksh, zsh and bash), on unix, macOS and Windows WSL.

1. The install script adds nvm to ~/.nvm and your profile
2. nvm install 22 fetches that version of Node.js
3. nvm use 22 points this shell’s PATH at it
4. A .nvmrc file names the version a project needs
5. nvm use with no version reads that file

Who it suits

Developers who work on several Node.js projects and need a different version in each. Maintainers who test a library on an old and a new Node.js get the same help, and so do people who build Docker images or CI jobs. Skip it on Windows outside WSL, Git Bash and Cygwin. For that the README points to nvm-windows, nodist and nvs, which it says the nvm team neither supports nor develops.

Where to use it

nvm runs in a POSIX-compliant shell on the platforms below, and the setup notes have a page for each of them, with the commands copied from the maker’s README.

• Linux: the install script with curl or wget, or a Git install
• macOS: the same script, after the Xcode command line tools are installed
• Windows: through WSL, and the README says it should also work in Git Bash or Cygwin
• Docker and CI jobs: set BASH_ENV, or use the README’s Dockerfile for CI/CD jobs
• Alpine Linux: extra packages first, and a source build when no musl binary exists
• Shells: sh, dash, ksh, zsh and bash. fish is not supported, and the README lists alternatives made by others

How to set it up

Get it saves a zip of Mindket’s setup notes in your downloads folder, with a page for each platform from the maker’s README. The install script does most of the work.

1. Run the install script with curl or wget.
2. Close the terminal and open a new one, or source your profile file.
3. Run command -v nvm, which should print nvm.
4. Install a Node.js version with nvm install.

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

The command names v0.40.8, the release the README named when these notes were written. Use the one it shows now. The script puts nvm in ~/.nvm, with git if you have it and a download if not, and adds the source lines to the profile file it finds. If it picks the wrong file, set the PROFILE variable to the right path and run it again.

command -v nvm

How to use it

Install a version, switch to it and set the default for new shells. The README says the first version you install becomes the default.

nvm install node
nvm install 14.7.0
nvm use node
nvm ls
nvm alias default node

The first line installs the latest release and the second installs that exact one, so a current copy and an older one can sit side by side on the same machine. Running nvm use changes PATH in the shell you run it in, and nvm ls lists what you have. A new shell starts on the default alias. For a project, put the version in a .nvmrc file. Then nvm use with no version reads it, and so do nvm install and nvm which.

Example

You have projects on Node.js 24, 22 and 20. This is the README’s first example. nvm use switches only to versions you have already installed, so 22 and 20 must be there first:

nvm install 24
node -v
nvm use 22
node -v
nvm use 20
node -v

Each node -v prints the version you just switched to. The README’s sample output also shows a Now using node line, with the node and npm versions, after each install and use.

For newcomers and experts

If you are new. A project can need a different Node.js than the one on your machine. nvm keeps each version in its own folder under ~/.nvm and changes which one your shell finds first. The nvm command is a function your shell loads, not a program on your PATH, so, as the README says, which nvm will not work. Use command -v nvm instead. Close the terminal after installing and open a new one. Until then the command may be missing. The README says that with nvm you do not need sudo to install a module globally with npm -g.

For experts. The special aliases (node, iojs, stable, unstable, current) work with nvm install, nvm use, nvm run, nvm exec and nvm which. LTS names (--lts, lts/*, lts/argon) work with install, uninstall, use, exec, run, ls-remote and version-remote. The commands nvm install --lts and nvm use with lts/*, and a .nvmrc line of lts/*, all follow the latest LTS. Every command that selects versions takes --only= with the categories alpha, lts, non-lts and iojs, and NVM_ONLY sets the default. Adding --reinstall-packages-from=current to nvm install reinstalls your global packages on the new version.

NVM_NODEJS_ORG_MIRROR and NVM_IOJS_ORG_MIRROR point nvm at a mirror of the binaries. NVM_AUTH_HEADER sends an Authorization header to a mirror, never to any other host, except that BusyBox’s wget, the README says, sends it wherever the mirror redirects. The README recommends curl for a mirror that hands downloads to another host. A default-packages file in NVM_DIR lists the packages you want installed with every new version, one name per line. You can add anything npm would accept as a package argument on the command line. Adding -s to nvm install builds from source, and setting NVM_NO_SOURCE_FALLBACK to 1 makes a missing binary an error instead of a silent source build. A per-version lock stops two shells from installing the same version at once.

Good to know

nvm is installed per user and runs in your own shell, but its install steps write to your profile file and fetch files from the network.

• Profile files: the install script appends source lines to the profile file it finds, and a bash_completion line to a bash or zsh profile. PROFILE=/dev/null keeps it from editing a profile
• Downloads: nvm fetches Node.js from nodejs.org, or from the mirror you set. The README’s sample install output shows a checksum step, Computing checksum with sha256sum and then Checksums matched
• Credentials: NVM_AUTH_HEADER goes only to mirror URLs with curl, which nvm prefers, and with GNU Wget. The README says BusyBox’s wget sends it wherever the mirror redirects. nvm prints mirror URLs that carry credentials with them masked as ***@
• Building from source: when no binary exists nvm compiles Node.js, which is slow and needs a C++ toolchain
• One user: nvm is available only to the account that installed it, so other users on the machine do not see it
• Not supported: the README says Homebrew installs and the fish shell are not supported, and it calls the Windows tools it lists instead unsupported by the nvm team. Only the latest nvm release is supported
• Settings that clash: a prefix in ~/.npmrc, the NPM_CONFIG_PREFIX and PREFIX variables, and set -e cause issues
• Removal: the README gives manual steps. Run nvm unload, delete the install directory, then remove the nvm lines from your profile
• License: MIT. The LICENSE.md file names Tim Caswell (2010) and Jordan Harband (2014), and the README’s copyright notice names the OpenJS Foundation and nvm contributors