nvm — User Guide

nvm (Node Version Manager) is a POSIX-compliant bash script that lets you install, switch between, and manage multiple Node.js versions in a single shell environment. It is sourced into your shell — not installed as a system binary — so each shell session can independently select its active Node.js version.

1. Quick Start

Tip

The fastest path: install nvm, then install the latest LTS Node.js in two commands.

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

# Open a new terminal, then install and use the latest LTS Node.js
nvm install --lts

Installing latest LTS version.
Downloading and installing node v22.x.x...
Now using node v22.x.x (npm v10.x.x)

What you get:

• Install and switch Node.js versions per project
• Per-project version pinning via .nvmrc
• LTS line management (lts/*, lts/iron, etc.)
• Global npm package reinstallation across upgrades
• Zero root permissions required

Prerequisites: bash or zsh, plus either curl or wget (and optionally git).

Next steps: See Installation for all install methods, or jump to Core Usage for the command reference.

2. Installation

System Requirements

Important

nvm does not support Windows natively. On Windows, use WSL (Windows Subsystem for Linux) or Git Bash. A PowerShell port has been requested (issue #3270) but is not implemented in this version.

Install Methods

curl

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

wget

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

git

git clone https://github.com/nvm-sh/nvm.git ~/.nvm
cd ~/.nvm && git checkout v0.40.4

The installer automatically detects your shell and appends the loader to your profile (.bashrc, .bash_profile, .zshrc, or .zprofile).

What the Installer Does

The installer appends two blocks to your shell profile:

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

# For bash/zsh — also appended:
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # Tab completion

Warning

If the installer cannot find a profile file, it prints the lines above and asks you to add them manually. Check ~/.bashrc, ~/.bash_profile, ~/.zshrc, or ~/.profile.

Post-Install Verification

# Close and reopen your terminal, then:
nvm --version

0.40.4

Custom Install Directory

Set NVM_DIR before running the installer to change where nvm is installed:

export NVM_DIR="$HOME/.config/nvm"
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash

macOS Note

If you see an error about Xcode Command Line Tools on macOS:

xcode-select --install

Then re-run the nvm installer.

3. Configuration

Environment Variables

Set these in your shell profile before sourcing nvm.sh.

Default Packages File

Create $NVM_DIR/default-packages (one package per line) to have nvm automatically install those packages whenever you install a new Node.js version:

typescript
nodemon
prettier

Tip

This file is read at install time. If you add packages later, use nvm reinstall-packages <old-version> to sync them to an already-installed version.

.nvmrc Files

Place a .nvmrc file in a project directory to pin the Node.js version. Running nvm use, nvm install, nvm run, or nvm exec without a version argument will read this file automatically.

# Pin to a specific version
echo "v22.4.0" > .nvmrc

# Pin to latest LTS
echo "lts/*" > .nvmrc

# Use it
nvm use        # reads .nvmrc

nvm walks up the directory tree to find the nearest .nvmrc.

4. Core Usage

Version Patterns

nvm accepts flexible version strings anywhere <version> appears:

Installing Node.js

# Install latest stable
nvm install node

# Install latest LTS
nvm install --lts

# Install specific LTS line
nvm install --lts=iron

# Install specific version
nvm install 20.11.0

# Install and make it the default
nvm install --lts --default

# Install and write version to .nvmrc
nvm install 22 --save

# Install and upgrade npm to the latest working version
nvm install 22 --latest-npm

# Install and carry over global packages from another version
nvm install 22 --reinstall-packages-from=20

# Install from binary only (skip source build attempt)
nvm install 22 -b

# Install from source only (skip binary download)
nvm install 22 -s

# Install without network (use cached download)
nvm install 22 --offline

Note

-s (source only) and -b (binary only) are mutually exclusive. Combining them produces an error.

Switching Versions

# Use a version
nvm use 22
nvm use --lts
nvm use node          # latest stable

# Use version from .nvmrc
nvm use

# Switch silently (no output)
nvm use --silent 22

# Switch and write to .nvmrc
nvm use --save 22

Now using node v22.4.0 (npm v10.7.0)

Warning

nvm use only affects the current shell session. Open a new terminal and you get the default alias. To make a version persist, set it as the default: nvm alias default 22.

Listing Versions

# List all installed versions
nvm ls

# List all remote versions available for install
nvm ls-remote

# List only LTS remote versions
nvm ls-remote --lts

# List only a specific LTS line
nvm ls-remote --lts=iron

# Show currently active version
nvm current

# Resolve a version string locally
nvm version 22

# Resolve a version string from the remote index
nvm version-remote 22
nvm version-remote --lts

# nvm ls output example
       v20.11.0
->     v22.4.0
         system
default -> lts/* (-> v22.4.0)
node -> stable (-> v22.4.0) (default)
stable -> 22.4 (-> v22.4.0) (default)
iojs -> N/A (default)
lts/* -> lts/jod (-> v22.4.0)

Aliases

# List all aliases
nvm alias

# Create an alias
nvm alias work-node 18.20.3

# Use an alias
nvm use work-node

# Delete an alias
nvm unalias work-node

# Set the default version
nvm alias default 22
nvm alias default node    # always use latest stable

Note

Built-in aliases (node, stable, unstable, iojs, system) cannot be deleted with nvm unalias. Custom aliases support any name except those containing /, #, or uppercase letters when the file system is case-sensitive (see issue #3764).

Running Commands on a Specific Version

# Run node with arguments using a specific version
nvm run 18 app.js
nvm run --lts app.js

# Execute any command with a specific version in PATH
nvm exec 18 node --version
nvm exec --lts node app.js

# Show path to the node binary for a version
nvm which 22
nvm which system
nvm which          # reads .nvmrc

/home/user/.nvm/versions/node/v22.4.0/bin/node

Uninstalling Versions

nvm uninstall 18.20.3
nvm uninstall --lts
nvm uninstall --lts=hydrogen

5. Common Tasks

Set Up a New Project

cd my-project
echo "22" > .nvmrc
nvm install
nvm use
npm init -y

Upgrade npm on the Current Node

nvm install-latest-npm

Carry Global Packages to a New Version

# Install new version, migrating packages from old
nvm install 22 --reinstall-packages-from=20

Or after the fact:

nvm use 22
nvm reinstall-packages 20

Check Which Version Is Active

nvm current
node --version

Use a Mirror (Corporate/Air-Gapped)

export NVM_NODEJS_ORG_MIRROR=https://your-mirror.example.com/nodejs
nvm install 22

Suppress All nvm Output

nvm use --silent 22
nvm exec --silent 18 node app.js

Customize Terminal Colors

# Format: 6 color codes — installed, system, current, not-installed, default, lts
nvm set-colors cgYmW

# Disable colors entirely
nvm ls --no-colors

Available color codes: r/R red/bold, g/G green/bold, b/B blue/bold, c/C cyan/bold, m/M magenta/bold, y/Y yellow/bold, k/K black/bold, e/W light grey/white.

Remove nvm Completely

# Remove the installation directory
rm -rf "$NVM_DIR"
# Then remove the nvm loader lines from your shell profile

Deactivate nvm for the Current Session

nvm deactivate           # removes nvm from PATH for this session
nvm unload               # unloads nvm functions entirely from shell

6. Troubleshooting

Error: nvm: command not found

Cause: nvm is not sourced in the current shell.

Solution:

1. Close and reopen your terminal.
2. If that doesn't work, verify the loader is in your profile:

   grep 'nvm.sh' ~/.bashrc ~/.bash_profile ~/.zshrc 2>/dev/null
   

3. If missing, add it manually:

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

4. Reload: source ~/.bashrc (or your profile file).

Prevention: Always source nvm in the correct profile for your shell (.zshrc for zsh, .bashrc for bash).

Error: N/A: version "22" is not yet installed

Cause: The requested version is not installed locally.

Solution:

nvm install 22

Error: Version 'x.y.z' not found - try 'nvm ls-remote'

Cause: The version doesn't exist in the Node.js distribution index.

Solution:

nvm ls-remote 22    # see available 22.x.x versions

nvm ls Outputs ANSI Color Codes When Piped

Cause: nvm detects terminal type, but piped output still shows escape codes in some configurations (issue #2497).

Solution:

nvm ls --no-colors | grep v22

Error: Profile not found. Tried ~/.bashrc, ~/.bash_profile, ...

Cause: The installer couldn't find a writable shell profile.

Solution:

1. Create the appropriate profile: touch ~/.bashrc
2. Re-run the install script, or manually add the loader lines shown by the installer.

nvm use Has No Effect After Opening a New Terminal

Cause: nvm use is session-scoped. The new terminal uses the default alias.

Solution:

# Make a version the persistent default
nvm alias default 22

# Or pin a project with .nvmrc and source nvm in --install mode

Error: You need git, curl, or wget to install nvm

Cause: None of the required download tools are available.

Solution:

# On Ubuntu/Debian
sudo apt install curl git

# On macOS
xcode-select --install   # includes git and curl

macOS: Failed to fetch origin or Git Errors

Cause: Xcode Command Line Tools are missing or outdated.

Solution:

xcode-select --install

Error: Unbound variable: PATTERN (bash strict mode)

Cause: Running nvm in a shell with set -u (nounset) active (issue #3820).

Solution: Source nvm before enabling set -u, or use a subshell. This is a known upstream issue.

nvm-exec Does Not Use the default Alias

Cause: nvm-exec requires NODE_VERSION to be set explicitly (issue #3810).

Solution:

NODE_VERSION="$(nvm version default)" "$NVM_DIR/nvm-exec" node app.js
# Or simply:
nvm exec default node app.js

7. FAQ

Q: Does nvm work on Windows?

nvm does not support native Windows. Use WSL (Windows Subsystem for Linux) or Git Bash. See issue #3270 for PowerShell support status.

Q: How do I make a specific Node.js version the default for all new shells?

nvm alias default 22
# or always track latest:
nvm alias default node

Q: Can I use nvm with sudo?

No. nvm installs Node.js into $NVM_DIR under your home directory. Global npm packages installed with nvm do not require sudo. If you need system-wide Node, install it via your OS package manager instead.

Q: How do I pin a project to a specific Node.js version?

Create .nvmrc in the project root:

echo "v22.4.0" > .nvmrc
nvm use   # reads .nvmrc automatically

Q: How do I install global npm packages automatically with each new Node version?

Create $NVM_DIR/default-packages with one package name per line. nvm reads this file after every nvm install.

Q: What is lts/* vs lts/iron?

lts/* always resolves to the latest LTS version across all lines. lts/<name> pins to a specific named LTS line (e.g., lts/iron = Node 20.x). Run nvm ls-remote --lts to see available LTS lines.

Q: How do I uninstall nvm?

Remove the installation directory and the loader lines from your profile:

rm -rf "$NVM_DIR"
# Edit ~/.bashrc (or ~/.zshrc) to remove the nvm export/source lines

Q: Does nvm work with io.js?

Yes. nvm supports io.js versions using the iojs prefix: nvm install iojs-v3.3.1, nvm use iojs. However, io.js is long deprecated; this is legacy support.

Q: Can I run two Node versions simultaneously?

Not in the same shell. Each shell session has one active version. Use separate terminal sessions or use nvm exec <version> <cmd> to run a one-off command under a different version without switching the shell.

Q: Why is npm slow to start in bash/zsh?

This is a known issue (#3811). npm's startup time is unrelated to nvm itself but can be noticeable in shells that load nvm on startup. Profiling your shell startup (zsh --zprof or bash --debug) can identify the source.