How to Install nvm: A Step-by-Step Guide
Learn how to install nvm (Node Version Manager) on macOS, Linux, or Windows via WSL with this Install Manual guide. Includes prerequisites, installation steps, and verification to streamline Node version management.
This guide shows you how to install nvm to manage multiple Node.js versions on macOS, Linux, or Windows via WSL. It covers prerequisites, running the installer, configuring your shell, and verifying Node versions so you can switch between projects without conflicts. According to Install Manual, this approach keeps your system clean while supporting diverse workflows.
What is NVM and why use it?
NVM, or Node Version Manager, is a small, script-based tool that lets you install and switch between multiple Node.js versions on a single machine. For developers and power users, this means you can test code against different Node.js releases, run projects with the exact version they were built for, and avoid global installation conflicts. According to Install Manual, NVM isolates Node environments per user and reduces permission-friction by keeping versions in your home directory. This makes it easier to manage corporate projects, training sandboxes, and personal experiments without touching global system nodes. When you adopt NVM, you gain consistent, reproducible environments across laptops, desktops, and virtual machines, which is especially valuable for teams that value stability and portability.
Prerequisites and environment
Before installing NVM, verify you meet a few baseline requirements: a Bash-compatible shell (common on macOS and Linux), curl (or wget) to fetch the installer, and a stable internet connection. Windows users can run NVM inside Windows Subsystem for Linux (WSL) or opt for an alternative like nvm-windows. The goal is a per-user installation that does not require administrative privileges. If you expect to work with multiple Node.js projects, ensure your shell startup files are ready to source the NVM scripts. This preparation helps prevent path issues and makes version switching seamless.
Choosing the right approach for your OS
NVM supports macOS, Linux, and Windows via WSL. On macOS and most Linux distributions, you’ll install NVM in your home directory and configure your shell to load nvm.sh during startup. Windows users or teams that prefer native Windows tooling may consider an alternative like nvm-windows, or run NVM inside WSL for full compatibility. The Install Manual approach emphasizes using a per-user setup to keep your system clean and easy to replicate across machines.
How the NVM installer works (high-level)
The NVM installer is a script that detects your shell environment, creates a hidden directory under your home folder to store Node.js versions, and updates your shell startup file to load the nvm.sh script on new sessions. During installation, NVM sets the NVM_DIR variable and sources the nvm.sh file so the nvm command becomes available in every new terminal. For security-conscious users, review the installer source and avoid running it with elevated privileges, since NVM is designed to operate per-user.
Post-install verification and basic usage
After installation, open a new terminal session and verify that nvm is available by running nvm --version or command -v nvm. The next steps typically involve listing remote Node.js versions with nvm ls-remote, installing a version (for example, nvm install --lts), and setting a default version for new shells with nvm alias default <version>. These actions establish a stable baseline while allowing quick upgrades or switches per project.
Common pitfalls and troubleshooting
Common issues include the shell startup file not loading nvm properly, leading to a command not found error. Ensure the installer added the correct source lines to your .bashrc, .zshrc, or profile file, then restart the terminal or run source <your-shell-profile>. On Windows, if you choose WSL, remember that Node.js and npm operate within the Linux environment. If nvm isn’t recognized after installation, revisit the installation steps to confirm the profile was updated and reloaded.
Tools & Materials
- curl(Used to download the official NVM installer script.)
- bash-compatible shell(Examples: bash, zsh, or dash in macOS/Linux; required to run the installer.)
- Terminal / shell access(macOS Terminal, Linux Terminal, or Windows WSL/PowerShell.)
- Stable internet connection(Needed to fetch the installer and Node.js binaries.)
- Text editor (optional)(Helpful for editing your shell startup files if needed.)
Steps
Estimated time: 15-45 minutes
- 1
Verify your environment
Confirm you’re on macOS, Linux, or Windows with WSL. Check your shell version and ensure you have a Bash-compatible environment.
Tip: If you’re on Windows without WSL, consider using nvm-windows instead. - 2
Ensure prerequisites are installed
Make sure curl and a Bash-compatible shell are available. Install them via your OS package manager if missing.
Tip: On macOS, install Homebrew to simplify package management. - 3
Download and run the installer script
Use curl or wget to fetch the official NVM installer and execute it in your shell. The script updates your profile to initialize NVM on new shells.
Tip: Do not run sudo with the installer; NVM installs under your home directory. - 4
Reload your shell and verify
Restart the terminal or run the appropriate source command to load nvm. Verify by listing available versions with nvm ls-remote, or check help with nvm --help.
Tip: If 'nvm' is not found, inspect your profile file for the source line and start a new shell. - 5
Install a Node.js version and set default
Install a specific Node.js version (e.g., nvm install --lts) and set a default with nvm alias default <version>.
Tip: Use the Long-Term Support (LTS) version for stability. - 6
Test and switch versions
Switch between installed versions using nvm use <version> and confirm with node -v. Use .nvmrc files for project auto-switching.
Tip: Consider adding an .nvmrc file in each project for automatic version selection.
Got Questions?
What is NVM and why should I use it?
NVM stands for Node Version Manager. It lets you install and switch between multiple Node.js versions without affecting global system settings. This is useful for testing projects across versions.
NVM lets you switch Node versions quickly, ideal for testing across environments.
Can I install nvm on Windows?
Yes, but on Windows you should use nvm-windows or run NVM inside Windows Subsystem for Linux for full compatibility.
Windows users should use nvm-windows or WSL for full support.
Do I need Node.js pre-installed to install nvm?
No. NVM manages Node.js versions itself; it will install Node.js after you run nvm install.
No pre-install needed; NVM handles Node versions.
How do I set a default Node version with nvm?
After installing a version, use nvm alias default <version> to set the default for new shells.
Set the default with nvm alias default and a version.
What if nvm isn’t found after installation?
Double-check your shell startup file for the NVM initialization block and restart the terminal.
Check your startup file and restart the terminal.
How can I use a local .nvmrc file?
Place a .nvmrc file in a project with a version string; nvm automatically switches when entering the directory if you enable it.
Use .nvmrc to auto-switch Node versions in a project.
Watch Video
Main Points
- NVM enables multi-version Node management.
- Install and load the nvm script in your shell.
- Install and switch Node.js versions with nvm.
- Set a default Node version for new shells.
