nvm — Fast Node Version Manager for POSIX Shells

Introduction

nvm (Node Version Manager) is a POSIX-compliant shell script that lets you install and manage multiple active Node.js versions on a single machine. It is the de-facto standard for switching Node runtimes across projects without polluting global paths.

What nvm Does

• Installs any published Node.js version with a single command
• Switches the active Node version per terminal session
• Reads .nvmrc files to auto-select the correct version per project
• Keeps each version's global npm packages isolated
• Works on macOS, Linux, and WSL without root privileges

Architecture Overview

nvm is implemented entirely in shell script (bash/zsh compatible). It manipulates the PATH environment variable to point at a versioned Node.js install directory under ~/.nvm/versions/node/. When you run nvm use, it simply re-prefixes your PATH so that the chosen binary directory comes first. No daemon or background service is involved.

Self-Hosting & Configuration

• Install via the official curl one-liner that appends nvm init to your shell profile
• Set NVM_DIR to customize the install location (default ~/.nvm)
• Create a .nvmrc file per project containing just a version string like 20 or lts/iron
• Run nvm alias default <version> to set the version for new shells
• Use nvm install-latest-npm after switching to ensure npm is current

Key Features

• Zero-dependency pure shell script with no compiled binaries
• Supports LTS aliases (--lts, lts/hydrogen) for convenience
• Per-project version pinning via .nvmrc
• Tab completion for bash and zsh
• Can install from source with nvm install -s <version>

Comparison with Similar Tools

• fnm — written in Rust for faster startup; nvm has broader adoption and longer track record
• asdf — multi-language version manager; nvm is Node-specific with deeper Node ecosystem integration
• Volta — handles package binaries and pinning in package.json; nvm is simpler and shell-native
• n — interactively manages Node versions globally; nvm provides per-shell isolation
• mise — polyglot dev tool manager; nvm remains the most widely documented choice for Node

FAQ

Q: Does nvm work on Windows natively? A: No. nvm is a POSIX shell script. On Windows, use WSL or the separate nvm-windows project which is a different codebase.

Q: How do I auto-switch Node versions when I cd into a project? A: Add nvm use to a shell hook or enable deeper shell integration (e.g., the cdnvm snippet from the README) that reads .nvmrc on directory change.

Q: Does switching versions affect globally installed npm packages? A: Yes. Each Node version has its own global node_modules. Use nvm reinstall-packages <old-version> to migrate them.

Q: Can I use nvm in CI/CD pipelines? A: Yes, but many CI services pre-install Node via other means. Source nvm.sh in your CI script and call nvm install to set the version from .nvmrc.

Sources

• https://github.com/nvm-sh/nvm
• https://github.com/nvm-sh/nvm#readme