How to Install NVM: A Practical Guide

Node Version Manager, commonly known as nvm, is an essential tool for anyone who works with Node.js across multiple projects or environments. By letting you install, switch between, and manage multiple Node.js versions from one place, nvm eliminates the friction of updating globally or running into compatibility issues. This guide walks you through installing nvm on macOS, Linux, and Windows (via the Windows-friendly variant), and shows practical how-tos to get you started quickly. Whether you are setting up a fresh development workstation or maintaining a large codebase with varying Node.js requirements, nvm can simplify your workflow.

What is Node Version Manager?

Node Version Manager is a lightweight, shell-based utility that tracks several Node.js installations. Instead of forcing a single system-wide Node.js version, you can install multiple versions—such as 12.x, 14.x, or 16.x—and switch between them on demand. This is especially useful when you work on projects with different runtime requirements or when you need to test how a project behaves under newer Node.js releases. With nvm, you can:

• Install and remove Node.js versions without affecting other projects.
• Set a default Node.js version for new shells.
• Quickly switch to a project-specific version using a simple command.
• Keep your environment clean by avoiding global npm packages tied to a single Node.js version.

Prerequisites

Before installing nvm, there are a few prerequisites to ensure a smooth setup. The official installation script relies on a Unix-like shell environment, so macOS, Linux, and Windows Subsystem for Linux (WSL) are the typical targets. Make sure you have:

• A terminal with a POSIX-compliant shell (bash, zsh, or similar).
• curl or wget installed to fetch the installer script.
• Access to your user profile files (such as .bashrc, .bash_profile, or .zshrc) to load nvm in new sessions.

If you’re working on a standard macOS or Linux machine, you’re likely already meeting these prerequisites. On Windows, you’ll want to use the nvm-windows project instead of the original nvm script, since the latter targets Unix-like environments. The Windows variant provides a similar experience with dedicated installers and environment setup steps.

Installation methods for Unix-like systems

The official installation approach for nvm on macOS or Linux centers on a simple curl or wget command that downloads the install script from the nvm repository and executes it in your shell. This script clones the nvm repository into your home directory and updates your profile to initialize nvm whenever a terminal session starts.

Method A: Using curl

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

After running the command, close and reopen your terminal, or source your profile to activate nvm in the current session. The exact profile file depends on your shell:

• bash: source ~/.bashrc or source ~/.bash_profile
• zsh: source ~/.zshrc
• fish: use the fish-specific init, as nvm is predominantly a bash-like script

Once loaded, you can verify the installation by checking the version of nvm:

nvm --version

Method B: Using wget

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

The wget approach does the same thing as curl, and the rest of the steps are identical. If you encounter permission or network-related issues, ensure your user account has the necessary rights and that your network allows fetching from GitHub.

Installing Node versions with nvm

With nvm installed, you can begin installing Node.js versions. The typical workflow involves listing available versions, installing a chosen version, and then configuring a default version. Here are common commands you’ll likely use frequently:

• nvm install --lts to install the latest Long-Term Support release.
• nvm install 18 to install Node.js version 18.x (or any specific major version).
• nvm ls-remote to view all available versions published by Node.js.
• nvm use 18 to switch to version 18 for the current session.
• nvm alias default 18 to make version 18 the default in new shells.

When you install a new Node.js version with nvm, npm (the Node package manager) is installed alongside it in the respective version’s runtime. This means your global npm packages are effectively version-specific, helping you avoid cross-project conflicts.

Post-installation steps

After the initial setup, some users need to explicitly add nvm initialization to their shell startup file. The installer usually does this automatically, but in case you don’t see nvm commands working in a fresh terminal, add the following lines to your profile (as appropriate for your shell):

export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm

Restart your terminal or source the profile, then test with nvm ls or nvm --version.

Practical usage tips

Here are a few practical tips for everyday use with nvm. They help you keep project environments consistent and reduce friction when onboarding new developers:

• Use nvm install --lts to stay aligned with actively supported Node.js releases.
• Keep a project-specific version by creating a .nvmrc file in the project root with a single line, such as 14 or 18. Then run nvm use in the project directory to switch automatically.
• Regularly update the nvm tool itself by repeating the installation command; the script checks for newer versions in the repository.
• Combine nvm with your package manager to test new Node.js versions on local branches before deploying to production.

Common troubleshooting scenarios

Some setups may require extra steps if you encounter trouble with nvm commands or environment variables. Common issues include:

• nvm: command not found — ensure your profile was updated and reloaded, or manually source the nvm script as shown above.
• Node.js version not found after install — verify you typed the version correctly and that your internet connection allowed the fetch.
• Shell incompatibilities — if you use a minimal shell, certain scripts may not load automatically; consider switching to a more fully featured shell like bash or zsh for day-to-day development.

Windows users: a quick note

For Windows developers, the traditional nvm script is not the recommended path. Instead, use the nvm-windows project, which provides an installer and a similar command surface for managing Node.js versions on Windows. The workflow mirrors the Unix-like experience, using commands such as nvm install, nvm use, and nvm ls, adjusted for Windows paths and conventions.

Best practices for teams and projects

To maximize reliability when multiple developers contribute to a single project, consider the following approaches:

• Commit an .nvmrc file at the project root with the exact Node.js major version you rely on. This helps new contributors switch quickly to the correct runtime with nvm use.
• Document the required Node.js version in your README, along with any npm or yarn considerations for that version.
• Automate environment setup in your onboarding scripts to install nvm (where appropriate) and switch to the project’s version automatically.

Cross-platform considerations

Although the installation process is similar on macOS and Linux, there are small differences in shell configuration paths and profile files. On macOS with the default zsh shell in recent releases, you will typically add initialization lines to ~/.zshrc. On Linux, the file may be ~/.bashrc or ~/.profile, depending on your distribution and how your shell starts new sessions. In Windows environments using WSL, the same Unix-like steps apply inside the Linux subsystem, which unifies the workflow with your other machines.

Conclusion

Installing Node.js versions with nvm is a robust, scalable approach for modern JavaScript development. By isolating Node.js versions per project or workflow, you reduce the risk of compatibility issues and simplify upgrades. The core commands—installing a version, selecting a default, and listing installed versions—cover most daily needs. As you gain experience with nvm, you’ll find it becomes a natural part of your development toolkit, reducing friction and enabling smoother collaboration across teams.