# 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.

```bash
# 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
```

```text
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](#2-installation) for all install methods, or jump to [Core Usage](#4-core-usage) for the command reference.

---

## 2. Installation

### System Requirements

| Requirement | Minimum |
|---|---|
| Shell | `bash` 3.2+ or `zsh` 5.0+ |
| Download tool | `curl` or `wget` |
| Git (optional) | Any version (enables git-based install) |
| OS | Linux, macOS, FreeBSD, OpenBSD, SunOS |

> [!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"
    ```bash
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
    ```

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

=== "git"
    ```bash
    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:

```bash
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

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

```text
0.40.4
```

### Custom Install Directory

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

```bash
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:

```bash
xcode-select --install
```

Then re-run the nvm installer.

---

## 3. Configuration

### Environment Variables

| Variable | Default | Purpose |
|---|---|---|
| `NVM_DIR` | `~/.nvm` (or `$XDG_CONFIG_HOME/nvm`) | nvm installation directory |
| `NVM_NODEJS_ORG_MIRROR` | `https://nodejs.org/dist` | Custom Node.js download mirror |
| `NVM_IOJS_ORG_MIRROR` | `https://iojs.org/dist` | Custom io.js download mirror |
| `NVM_NO_COLORS` | unset | Set to `--no-colors` to disable colored output |
| `NVM_AUTH_HEADER` | unset | Authorization header for authenticated mirror downloads |

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:

```text
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.

```bash
# 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:

| Pattern | Resolves to |
|---|---|
| `22` or `v22` | Latest installed v22.x.x |
| `22.4.0` or `v22.4.0` | Exact version |
| `node` | Latest stable Node.js |
| `stable` | Alias for `node` |
| `lts/*` | Latest LTS version |
| `lts/iron` | Latest version in the Iron LTS line |
| `system` | System-installed Node.js (outside nvm) |
| `default` | The current default alias |

### Installing Node.js

```bash
# 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

```bash
# 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
```

```text
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

```bash
# 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
```

```text
# 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

```bash
# 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

```bash
# 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
```

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

### Uninstalling Versions

```bash
nvm uninstall 18.20.3
nvm uninstall --lts
nvm uninstall --lts=hydrogen
```

---

## 5. Common Tasks

### Set Up a New Project

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

### Upgrade npm on the Current Node

```bash
nvm install-latest-npm
```

### Carry Global Packages to a New Version

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

Or after the fact:

```bash
nvm use 22
nvm reinstall-packages 20
```

### Check Which Version Is Active

```bash
nvm current
node --version
```

### Use a Mirror (Corporate/Air-Gapped)

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

### Suppress All nvm Output

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

### Customize Terminal Colors

```bash
# 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

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

### Deactivate nvm for the Current Session

```bash
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:
   ```bash
   grep 'nvm.sh' ~/.bashrc ~/.bash_profile ~/.zshrc 2>/dev/null
   ```
3. If missing, add it manually:
   ```bash
   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:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
# 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:**
```bash
# 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:**
```bash
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:**
```bash
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?**

```bash
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:
```bash
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:
```bash
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.

---

_Generated May 2026 from nvm-sh/nvm at f695512. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._