DOCSEARCHbyAlgolia
Submit Docs

nvm (Node Version Manager)

repository·master·Indexed 13 days ago

https://github.com/nvm-sh/nvm

A shell script for managing multiple active Node.js versions on a single machine. It allows developers to install, switch between, and manage Node.js versions via the command line. Compatible with POSIX-compliant shells (sh, dash, ksh, zsh, bash) on Unix, macOS, and Windows WSL. Version 0.40.6 supports .nvmrc files for project-specific versions, LTS release lines, and global npm package migration.

Tokens
5.1K
Snippets
22
Records
30
Agent score
50%

What's inside nvm

  1. What is nvm and which platforms does it support?

    master

    nvm is a version manager for Node.js designed to be installed on a per-user basis and invoked per-shell. It is compatible with any POSIX-compliant shell (including sh, dash, ksh, zsh, and bash) and is specifically designed to work on the following platforms:

    • Unix
    • macOS
    • Windows WSL (Windows Subsystem for Linux)

  2. Overview of nvm (Node Version Manager)

    master

    nvm is a version manager for Node.js designed to be installed per-user and invoked per-shell. It allows you to quickly install and switch between different versions of Node.js via the command line. It is compatible with any POSIX-compliant shell (sh, dash, ksh, zsh, bash) and works on Unix, macOS, and Windows WSL.

    $ nvm install 24
Now using node v24.14.0 (npm v11.9.0)
$ node -v
v24.14.0
$ nvm use 22
Now using node v22.22.1 (npm v10.9.4)
$ node -v
v22.22.1

  3. Use .nvmrc files for project-specific versions

    master

    You can place a .nvmrc file in your project root containing a version string (e.g., 18.12, lts/*, or node). When you run nvm use, nvm install, or nvm which without arguments, NVM will look for this file in the current or parent directories and use the specified version. If the version is not installed, nvm install will download it automatically.

    # Create a .nvmrc file
echo "lts/*" > .nvmrc

# NVM will now use the version in .nvmrc
nvm use

  4. Use special version aliases

    master

    Instead of specific version numbers, you can use several built-in aliases with commands like nvm install, nvm use, nvm run, etc.:

    • node: The latest version of Node.js.
    • iojs: The latest version of io.js.
    • stable: Currently an alias for node (deprecated).
    • unstable: Points to Node v0.11.
    • current: The version currently active in your shell (resolved via $PATH).
    • system: The system-installed version of Node.

  5. Run nvm tests

    master

    Tests for nvm are written in Urchin. To run them, first install dependencies using npm install. There are two types of tests:

    • Fast tests: Mock installations to test logic like aliases and uninstallation.
    • Slow tests: Perform actual Node installations and version checks.

    Note: Avoid running nvm commands while tests are in progress.

    # Install dependencies
npm install

# Run fast tests
npm run test/fast

# Run slow tests
npm run test/slow

# Run all tests
npm test

  6. Install Node.js offline

    master

    If a version is already in your local cache, you can install it without a network connection using the --offline flag. This is useful for air-gapped environments.

    nvm install --offline 14.7.0

  7. Automate Node version switching with .nvmrc

    master
    While NVM does not automatically switch versions when you change directories, you can use community recipes or tools like nvshim to automate this. Common methods involve adding shell functions to your .bashrc, .zshrc, or config.fish that trigger nvm use when a .nvmrc is detected during directory changes.

  8. Enable Bash Completion for nvm

    master

    To enable tab-completion for nvm commands, source the bash_completion file in your shell profile (e.g., .bashrc or .bash_profile). Place this line immediately after the line that sources nvm.sh.

    [[ -r $NVM_DIR/bash_completion ]] && \. $NVM_DIR/bash_completion

  9. Install and use Node.js versions

    master

    Use nvm install to download and install Node.js. You can install the latest version using the node alias, or specify a version number. Once installed, use nvm use to switch to a version in your current shell, or nvm run / nvm exec to run commands in a subshell with a specific version without switching the shell's active version.

    # Install latest version
nvm install node

# Install specific version
nvm install 14.7.0

# Use a specific version in current shell
nvm use 14.7.0

# Run a command in a subshell with a specific version
nvm run 14.7.0 --version
nvm exec 14.7.0 --version

  10. Install or update nvm using the install script

    master

    The recommended way to install or update nvm is to run the official install script via curl or wget. The script clones the nvm repository to ~/.nvm and attempts to add the necessary loading lines to your shell profile (e.g., ~/.bashrc, ~/.zshrc, ~/.bash_profile, or ~/.profile).

    Customization Options:

    • Directory: Set NVM_DIR to change the installation path (ensure no trailing slash).
    • Profile: Set PROFILE to specify which profile file to update. To prevent the script from editing any shell config files, set PROFILE=/dev/null.
    • Postpone usage: Add --no-use to the end of the command to prevent nvm from automatically using the default Node version upon loading.
    • Environment Variables: You can also use NVM_SOURCE, NODE_VERSION, etc., to customize the installation.
    # Using curl
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash

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

# Example: Custom directory and no auto-use
NVM_DIR="/path/to/nvm" curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash --no-use

  11. Install older Node.js versions on Apple Silicon (M1/M2/M3) Macs

    master

    Node.js versions prior to v16.0 do not have native Apple Silicon support. To run these versions, you must compile them for the x86_64 (Intel) architecture using Rosetta 2.

    Follow these steps:

    1. Install Rosetta 2 (if not already installed):

      softwareupdate --install-rosetta

    2. Open an Intel-based shell:

      arch -x86_64 zsh

      Note: If nvm is not automatically loaded in this new shell, manually source it: source "${NVM_DIR}/nvm.sh".

    3. Install the desired Node version using the --shared-zlib flag to avoid incorrect data check errors caused by certain versions of Apple's clang compiler:

      nvm install v12.22.1 --shared-zlib

    4. Verify the architecture: Exit the Rosetta shell and run the following in your native shell to ensure the Node binary is running as x64:

      node -p process.arch

      Expected output: x64.

    # 1. Install Rosetta
softwareupdate --install-rosetta

# 2. Enter Intel shell
arch -x86_64 zsh

# 3. Source nvm if needed
source "${NVM_DIR}/nvm.sh"

# 4. Install Node with shared-zlib flag
nvm install v12.22.1 --shared-zlib

# 5. Verify architecture
node -p process.arch

  12. Install nvm on Alpine Linux

    master

    Because Alpine Linux uses musl instead of the standard C library used by most Node.js binaries, pre-compiled binaries will not work. You must install dependencies and then use the nvm install script. Depending on your Alpine version, you may need python2 or python3 to build Node.js from source.

    Note: Use the -s flag with nvm install <version> to force a local compilation from source.

    # For Alpine Linux 3.13+
apk add -U curl bash ca-certificates openssl ncurses coreutils python3 make gcc g++ libgcc linux-headers grep util-linux binutils findutils
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash

# For Alpine Linux 3.5 - 3.12
apk add -U curl bash ca-certificates openssl ncurses coreutils python2 make gcc g++ libgcc linux-headers util-linux binutils findutils
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash