Managing Node.js Versions with nvm: Core Commands and Practical Operations

Why Node.js Needs Version Management

Node.js is a runtime environment for executing JavaScript on the server. It features an event-driven architecture and asynchronous processing, and it is used in a wide range of areas, from building web APIs to running frontend build tools. Along with package managers such as npm, it has become essential infrastructure in modern development.

Node.js can be installed with the official installer. In real projects, however, developers frequently need to switch between multiple versions. An existing system may run on Node.js 18 while a new project adopts Node.js 22. The Node Version Manager, or nvm, is useful in exactly these situations.

nvm installs Node.js under the user’s home directory and switches the active version according to the shell configuration. Its main advantage is that it can be installed without administrator privileges and does not affect the entire system.

How nvm Works

nvm is a version management tool implemented as shell functions. Running the official install script places the nvm scripts under the home directory, where they are loaded when the shell starts. Users can install, switch, and remove Node.js versions with a single command.

The main features of nvm are as follows.

• Install any Node.js version
• List installed versions
• Switch versions automatically per project
• Set the default version
• Uninstall versions that are no longer needed

Unlike the official installer, which affects the whole system, nvm keeps its environment under the home directory. Multiple versions can therefore coexist easily, and switching versions does not affect other development tools.

Installing nvm

On macOS and Linux

On macOS and Linux, download and run the official nvm install script with curl or wget. The script is published on GitHub, and the latest procedure is described in the README of the nvm-sh/nvm repository.

After installation, the following lines are added to the shell configuration file.

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

These lines load nvm when the shell starts. They go into .zshrc for zsh and .bashrc for bash. Restart the shell or reload the configuration file after installation.

On Windows

The standard nvm does not work in the Windows command prompt or PowerShell. On Windows, use the compatible tool nvm-windows. It is a separate project maintained by coreybutler and is installed with an installer from the official repository.

nvm-windows offers a command set similar to nvm, but its internals differ. It switches the Node.js path with symbolic links, which may require administrator privileges. Existing Node.js installations should be removed before installation to avoid path conflicts.

Verifying the Installation

After installation, check the nvm version with the following command.

nvm --version

If a version number appears, the installation succeeded. If the command is not found, verify that the shell configuration file loads nvm correctly.

Core nvm Commands

Installing a Version

List the available Node.js versions with the following command.

nvm ls-remote

Install a specific major version as follows.

nvm install 22

This installs the latest release in the Node.js 22 line. You can also specify a development build or a particular minor version.

nvm install 22.14.0

To select an LTS release explicitly, use the LTS flag.

nvm install --lts

Checking Installed Versions

List the installed versions with the following command.

nvm ls

The active version is marked with an arrow. When several versions are installed, you need to choose which one to use.

Switching Versions

Use the nvm use command to activate a specific version.

nvm use 20

The change affects only the current shell session. A new terminal starts with the default version.

Setting the Default Version

Set the version applied when a shell opens with the following command.

nvm alias default 22

After this, new shells load Node.js 22. Making the setting explicit is useful when onboarding new team members who need a common version.

Uninstalling a Version

Remove a version that is no longer needed with the following command.

nvm uninstall 18

Confirm that the version is not in use before uninstalling. Removing the active version produces an error.

Basic Node.js and npm Workflow

Installing Node.js with nvm also installs npm. npm is the standard Node.js package manager and is used to add libraries and run scripts.

Initializing a Project

Generate package.json first when starting a new project.

npm init -y

package.json records the project name, version, dependencies, and scripts. In team development, commit this file so the environment can be reproduced.

Installing Packages

Add dependencies with npm install.

npm install express

The package is unpacked into node_modules and added to the dependencies field in package.json. Packages needed only during development use the –save-dev option.

npm install --save-dev jest

Running Scripts

Commands defined in the scripts field of package.json run through npm run.

npm run test

Defining repetitive tasks such as linting, builds, and tests as scripts keeps the team’s procedure consistent.

The Role of package-lock.json

npm install generates package-lock.json automatically. The file fixes the exact versions of dependencies. Commit package-lock.json as well so that everyone uses the same package versions.

Practical Patterns for Project Operations

Pinning Versions with .nvmrc

Create an .nvmrc file in the project root to state the Node.js version to use.

22

Running nvm use in a directory with this file switches to the specified version automatically.

nvm use

.nvmrc plays an important role in team development. It prevents members from using the wrong Node.js version and narrows the gap between local and production environments.

The engines Field in package.json

The engines field in package.json can declare the range of Node.js versions the project supports.

"engines": {
 "node": ">=20 <23"
}

npm install shows a warning when this setting is violated. Because npm alone does not enforce it strictly, combine it with validation in CI.

Specifying Node.js in CI

In CI environments such as GitHub Actions, specify the Node.js version through a setup action. GitHub Actions commonly uses actions/setup-node with .nvmrc.

- uses: actions/setup-node@v4
 with:
 node-version-file: '.nvmrc'

This keeps the local and CI Node.js versions identical. nvm itself does not need to be installed in CI, because the setup action resolves the version.

Pitfalls When Using nvm

Because nvm runs as shell functions, the commands are unavailable if the configuration file fails to load when the shell starts. Since macOS moved its default terminal shell to zsh, missing entries in .zshrc have become a common cause. When troubleshooting, check the output of which node first. If the system Node.js takes precedence, review the path order.

Node.js installed with nvm also lacks the global npm configuration bundled with the official installer. If you rely on global packages, you may need to reinstall them after adopting nvm.

Editorial Opinion

When evaluating Node.js environment setup, we prioritize reproducibility per project and consistency across the team. nvm performs very well on both counts, and its low adoption cost and simple command set make it accessible to beginners. Leaving version pinning to .nvmrc alone, however, depends on each member’s discipline, so validation in CI should be mandatory.

A common pitfall in practice is losing access to existing global packages after installing nvm. On Windows in particular, nvm-windows combines administrator privileges with a different path layout and can behave unexpectedly. Survey the existing Node.js environment before installation and perform a clean install when necessary.

Going forward, watch for the possibility that version management is integrated into Node.js itself. Bun and Deno are widening runtime choices, while the ways to manage Node.js-compatible environments are also diversifying. nvm will remain a stable option, but teams should evaluate alternatives such as Volta and asdf according to project characteristics.

References

• Node.js official site
• nvm-sh/nvm GitHub repository
• coreybutler/nvm-windows GitHub repository
• npm documentation