Skip to content
1337skills 1337skills

NVM Cheat Sheet

Overview

NVM (Node Version Manager) is a POSIX-compliant bash script for managing multiple active Node.js versions on a single machine. It allows developers to install, switch between, and manage different Node.js versions per-project or globally, solving the common problem of projects requiring different Node.js versions.

NVM works by modifying the PATH to point to the selected Node.js installation directory. Each version is installed in an isolated directory under ~/.nvm/versions/node/, preventing conflicts between versions. NVM supports .nvmrc files for automatic version switching per project and integrates with shell initialization for seamless workflow integration.

Installation

# Install NVM (latest)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

# Or with wget
wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

# Reload shell configuration
source ~/.bashrc
# Or for zsh:
source ~/.zshrc

# Verify installation
nvm --version

# Manual install (add to ~/.bashrc or ~/.zshrc)
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

Core Commands

CommandDescription
nvm install <version>Install a specific Node.js version
nvm uninstall <version>Uninstall a version
nvm use <version>Switch to a version
nvm currentShow currently active version
nvm lsList installed versions
nvm ls-remoteList available remote versions
nvm alias <name> <version>Create a named alias
nvm run <version> <script>Run a script with a specific version
nvm exec <version> <command>Execute a command with a specific version
nvm which <version>Show path to a version’s node binary
nvm deactivateDeactivate NVM (revert PATH)

Installing Node.js Versions

# Install latest LTS
nvm install --lts

# Install latest version
nvm install node

# Install specific version
nvm install 20.11.0
nvm install 18.19.0
nvm install 22

# Install latest of a major version
nvm install 20

# Reinstall packages from another version
nvm install 20 --reinstall-packages-from=18

# Install with specific architecture
nvm install 20 --arch=x64

Switching Versions

# Use a specific version
nvm use 20.11.0
nvm use 20

# Use latest LTS
nvm use --lts

# Use latest installed
nvm use node

# Use system-installed Node
nvm use system

# Run a single command with a specific version
nvm run 18 --version
nvm exec 18 node -e "console.log(process.version)"

# Check which version is active
nvm current
node --version

Listing Versions

# List installed versions
nvm ls

# List remote versions available for install
nvm ls-remote

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

# List specific major version
nvm ls-remote 20

# List LTS by codename
nvm ls-remote --lts=iron   # Node 20 LTS
nvm ls-remote --lts=jod    # Node 22 LTS

Aliases

# Set default version (used in new shells)
nvm alias default 20

# Create custom alias
nvm alias my-project 18.19.0
nvm use my-project

# List all aliases
nvm alias

# Remove an alias
nvm unalias my-project

# Set default to latest LTS
nvm alias default lts/*

# Set default to latest
nvm alias default node

.nvmrc File

# Create .nvmrc in project root
echo "20" > .nvmrc

# Or with specific version
echo "20.11.0" > .nvmrc

# Or with LTS
echo "lts/*" > .nvmrc
echo "lts/iron" > .nvmrc

# Use version from .nvmrc
cd /path/to/project
nvm use
# Found '/path/to/project/.nvmrc' with version <20>

Auto-Switching (Shell Integration)

# Add to ~/.zshrc for automatic version switching
autoload -U add-zsh-hook
load-nvmrc() {
  local nvmrc_path
  nvmrc_path="$(nvm_find_nvmrc)"

  if [ -n "$nvmrc_path" ]; then
    local nvmrc_node_version
    nvmrc_node_version=$(nvm version "$(cat "${nvmrc_path}")")

    if [ "$nvmrc_node_version" = "N/A" ]; then
      nvm install
    elif [ "$nvmrc_node_version" != "$(nvm version)" ]; then
      nvm use
    fi
  elif [ -n "$(PWD=$OLDPWD nvm_find_nvmrc)" ] && [ "$(nvm version)" != "$(nvm version default)" ]; then
    echo "Reverting to nvm default version"
    nvm use default
  fi
}
add-zsh-hook chpwd load-nvmrc
load-nvmrc
# Add to ~/.bashrc for automatic version switching
cdnvm() {
  builtin cd "$@" || return
  nvm_path="$(nvm_find_nvmrc)"
  if [ -n "$nvm_path" ]; then
    nvm use > /dev/null 2>&1
  fi
}
alias cd='cdnvm'

Global Packages

# Install global package for current Node version
npm install -g typescript

# Reinstall global packages when switching versions
nvm install 22 --reinstall-packages-from=20

# List global packages for current version
nvm use 20
npm list -g --depth=0

# Default packages for new installs
# Create ~/.nvm/default-packages
echo "typescript" >> ~/.nvm/default-packages
echo "eslint" >> ~/.nvm/default-packages
echo "prettier" >> ~/.nvm/default-packages

Advanced Usage

Offline Install

# Download and cache Node.js for offline use
nvm install 20
# Binary is stored in ~/.nvm/versions/node/v20.x.x/

# Copy the .nvm directory to offline machine
# Then: nvm use 20

Mirror Configuration

# Use a custom Node.js mirror
export NVM_NODEJS_ORG_MIRROR=https://nodejs.org/dist
export NVM_IOJS_ORG_MIRROR=https://iojs.org/dist

# Chinese mirror
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node

Performance: Lazy Loading

# Lazy load NVM for faster shell startup
# Add to ~/.zshrc or ~/.bashrc
lazy_nvm() {
  unset -f nvm node npm npx
  export NVM_DIR="$HOME/.nvm"
  [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
  [ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"
}
nvm() { lazy_nvm; nvm "$@"; }
node() { lazy_nvm; node "$@"; }
npm() { lazy_nvm; npm "$@"; }
npx() { lazy_nvm; npx "$@"; }

Configuration

# Environment variables
export NVM_DIR="$HOME/.nvm"            # NVM installation directory
export NVM_NODEJS_ORG_MIRROR="..."     # Custom download mirror
export NVM_AUTO_USE=true               # Auto-use .nvmrc (some shells)

# Default packages file
# ~/.nvm/default-packages
# One package per line, installed with every new Node version

Troubleshooting

IssueSolution
nvm: command not foundSource NVM script: source ~/.nvm/nvm.sh; check shell profile
Version not switchingEnsure NVM is loaded; check for conflicting Node installations
Slow shell startupUse lazy loading technique to defer NVM initialization
.nvmrc not auto-switchingAdd shell hook (zsh/bash) for automatic version switching
Global packages missing after switchReinstall with --reinstall-packages-from=<version>
Permission errorsNVM installs to home directory; never use sudo with NVM
N/A versionVersion not installed; run nvm install to install from .nvmrc
Corepack not availableRun corepack enable after switching Node versions