Table of Contents
- Introduction
- About
-
- and upgrade script Additional Notes Troubleshooting
- Linux Troubleshooting
- in macOS
- Ansible
- Verify
- Important notes Git
- Installation
- Installation
- Using Updates
installation
Manual
Manual
- and upgrade script Additional Notes Troubleshooting
-
- Long-term support
- when installing
- default global packages from file during IO installation
- .js
- Node System Version Version
- List
-
- Custom color persistence
- Colored output suppression
- Restoring PATH
- Set the default version
- node binaries
of the node Use a mirror of the .nvmrc
-
-
-
- fish Call nvm Use automatically in a directory with an .nvmrc file
-
Running
-
Migrating global packages
Configuring custom colors
Deeper Shell Integration Bash Automatically call nvm use zsh Call nvm automatically use in a directory with a .nvmrc file
- testing
- Environment variables
- Bash Termination
- Usage compatibility
-
- + Alpine Linux 3.5 – 3.12
-
- Uninstalling/Removing Manual Uninstalling
- Docker For
- macOS Troubleshooting
- WSL Maintainer License
- Copyright Notice
installing and updating the installation
issues Installing nvm on
Alpine Linux Alpine Linux 3.13
development environment issues Troubleshooting
Introduction NVM allows you to quickly install and use different versions of Node via the command line. Example: It’s
that simple!
About
NVM
is a version manager for nodes.js, designed to be installed per user and invoked by shell. nvm works in any POSIX-compliant shell (sh, dash, ksh, zsh, bash), particularly on these platforms: unix, macOS and Windows WSL.
Installing
and updating the installation
and
upgrade script
To install or upgrade nvm, you must run the installation script. To do this, you can download and run the script manually or use the following cURL or Wget command:
When you run any of the above commands, a script is downloaded and executed. The script clones the nvm repository to ~/.nvm and attempts to add the source lines of the following code snippet to the correct profile file (~/.bash_profile, ~/.zshrc, ~/.profile, or ~/.bashrc).
Additional Notes
-
If the environment variable $XDG_CONFIG_HOME is present, it will place the nvm files there.
-
You can add -no-use to the end of the above script (… nvm.sh-no-use) to postpone using NVM until you use it manually.
-
You can customize the source, directory, profile, and installation version by using the variables NVM_SOURCE, NVM_DIR, PROFILE, and NODE_VERSION. Ex: curl … | NVM_DIR=”path/to/nvm”. Make sure the NVM_DIR does not contain a trailing forward slash.
-
The installer can use git, curl, or wget to download nvm, whichever is available.
Troubleshooting in
Linux
On Linux, after running the installation script, if you get nvm: command not found or see no comments from your terminal after typing command -v nvm, just close your current terminal, open a new terminal and try to check again. Alternatively, you can run the following commands for the different shells on the command line
: bash: source ~/.bashrc zsh: source ~/.
zshrc ksh: . ~/.
profile
These should pick up the nvm command
.
Since
OS X 10.9, /usr/bin/git has been preset by Xcode’s command-line tools, which means we can’t correctly detect whether Git is installed or not. You must manually install the Xcode command-line tools before running the installation script, otherwise it will fail. (view #1782)
If you get the nvm:
not found command after running the installation script, one of the following could be the reason:
-
Since macOS 10.15, the default shell is zsh and nvm will look for .zshrc to update, neither are installed by default. Create one with touch ~/.zshrc and run the installation script again.
-
If you use bash, the default shell above, your system might not have .bash_profile or .bashrc files where the command is configured. Create one of them with touch ~/.bash_profile or tap ~/.bashrc and run the installation script again. Then run . ~/.bash_profile or . ~/.bashrc to pick up the nvm command.
-
You’ve used bash before, but you have zsh installed. You must manually add these lines to ~/.zshrc and run . ~/.zshrc.
-
You may need to restart the terminal instance or run . ~/.nvm/nvm.sh. Restarting your terminal / opening a new tab / window, or running the source command will load the command and new settings.
-
If the above did not help, you may need to restart the terminal instance. Try opening a new tab/window in your terminal and try again.
If the
above doesn’t fix the problem, you can try the following:
-
If you use bash, your .bash_profile (or ~/.profile) may not get your ~/.bashrc correctly. You can fix this by adding the ~/<your_profile_file> source or follow the next step below.
-
Try adding the snippet from the installation section, which finds the correct nvm directory and loads nvm, to your usual profile (~/.bash_profile, ~/.zshrc, ~/.profile, or ~/.bashrc).
-
more information about this issue and possible solutions, see here
For
Note For Mac With the M1 chip, Node started offering arm64 arch darwin packages since v16.0.0 and experimental arm64 support when compiling from source code since v14.17.0. If you’re having trouble installing node using nvm, you might want to upgrade to one of those versions or later.
Ansible
You can use a task
:
Verify
installation To verify that nvm
has been installed, do: that
it should generate nvm if the installation was successful. Note that nvm will not work, as nvm is a source shell function, not an executable binary.
Note: On Linux, after running the installation script, if you get nvm: command not found or see no comments from your terminal after typing command -v nvm, just close your current terminal, open a new terminal and try to check again.
Important Notes
If you’re running a system
with no prepackaged binary available, meaning you’re going to install nodejs or io.js from your source code, you need to make sure your system has a C++ compiler. For OS X, Xcode will work, for Debian/Ubuntu-based GNU/Linux, the build-essential and libssl-dev packages work.
Note: nvm is also supported on Windows in some cases. It should work through WSL (Windows Subsystem for Linux) depending on the version of WSL. It should also work with GitBash (MSYS) or Cygwin. Otherwise, for Windows, there are some alternatives, which are not supported or developed by us
:
- nvm-windows
- nodist
- nvs
Note: nvm is also not compatible with Fish (see #303). There are alternatives, which are not supported or developed by us:
- Bass allows you to use utilities written for Bash
- Fast-NVM-fish only works with version numbers (not aliases) but does not significantly slow down your
- Oh My Fish, which makes nvm and its terminations available in Fish Shell
- FNM – Fisherman-based version manager for fish
- fish-nvm – Wrapping around fish nvm, delays nvm supply until it is actually used.
in Fish Shell
shell-nvm startup plugin for
Note: We still have some problems with FreeBSD, because there is no official pre-built binary for FreeBSD, and compiling from source code may need patching; see the issue ticket
: [#
- 900] [Bug] nodejs on FreeBSD may need to be patched nodejs
- /node#3716
Note: On OS X, if you don’t have Xcode installed and don’t want to download the ~4.3GB file, you can install the command-line tools. You can check out this blog post on how to do it
: How to install
- command-line tools in OS X Mavericks and Yosemite (without Xcode)
Note: In OS X, if you have/had a “system” node installed and want to install modules globally, please note that:
- When using nvm you do not need sudo to globally install a module with npm -g, So instead of doing sudo npm install -g grunt, do npm install -g grunt instead.
- If you have a ~/.npmrc file, make sure it doesn’t contain any prefix settings (which is not supported by
- You can (but shouldn’t?) keep the installation of the old “system” node, but nvm will only be available to your user account (the one used to install nvm). This may cause version discrepancies, as other users will use /usr/local/lib/node_modules/* VS your user account using ~/.nvm/versions/node/vX.X.X/lib/node_modules/*
nvm)
Homebrew installation is not supported. If you are having problems with nvm installed on homebrew, uninstall and install it by following the instructions below, before presenting a problem.
Note: If you are using zsh, you can easily install nvm as a zsh plugin. Install zsh-nvm and run nvm upgrade to upgrade.
Note: Git versions prior to v1.7
may face an issue of cloning nvm feeds from GitHub over https protocol, and there is also different git behavior before v1.6, and git prior to v1.17.10 cannot clone tags, so the minimum required version of git is v1.7.10. If you’re interested in the issue we mentioned here, check out the GitHub HTTPS clone errors article.
Git Install
If you have git installed (requires git v1.7.10+):
- Clone this repository to the root of your user profile cd ~/
- from anywhere, then git clone https://github.com/nvm-sh/nvm.git.
NVM CD ~
- nvm and check the latest version with git checkout v0.39.3
- Active NVM by getting it from your shell
/.
: . ./nvm.sh Now add these lines to your ~/.
bashrc, ~/.profile or ~/.zshrc file so that it is automatically obtained upon login: (You may need to add to more than one of the files above)
Manual installation
For a fully manual installation, run the following lines to first clone
the nvm repository to $HOME/.nvm, and then load nvm: Now add these lines to your ~/.
bashrc, ~/.profile, or ~/.zshrc so that it is automatically obtained when logging in: (you may need to add to more than one of the above files)
Manual
update For
manual update with git (requires git v1.7.10+):
- switch to $NVM_DIR
- Displays
- Check
the latest changes
out the latest version Activate the new version
Usage
To download, build, and install the latest version of the node
, do the following
:
To install a specific version of the node:
The first installed version becomes the default. New shells will start with the default version of the node (for example, the default nvm alias).
You can
list the available versions using ls-remote
: And then, in any new shell, just use the installed version: Or you can
simply run it
:
Or, you can run any arbitrary command in a subshell with the desired version of the node
:
You can also get the path to the executable where it was installed:
Instead of a pointer
of version such as “14.7” or “16.3” or “12.22.1”, You can use the following special default aliases with
nvm install, nvm use, nvm run, nvm exec, nvm which, etc: node: This installs the latest version of
- Node IOJS: This installs the latest version of IOD.js
- Stable: This alias is deprecated and only really applies to node v0.12 and earlier. Currently, this is an alias for node.
- Unstable: This alias points to node v0.11 – the latest “unstable” node version, since after 1.0, all node versions are stable. (In SemVer, versions communicate breakage, not stability.)
The
long-term support node
has a schedule for long-term support (LTS) You can reference LTS versions in aliases and .nvmrc files with the lts/* notation for the latest LTS version and lts/argon for LTS versions of the “argon” line, for example. In addition, the following commands support LTS arguments:
nvm install -lts / nvm install -lts=argon / nvm install ‘lts/*’ / nvm install lts/argon nvm uninstall -lts / nvm uninstall -lts=argon / nvm uninstall ‘lts/*’ / nvm uninstall lts/argon nvm use -lts / nvm use -lts=argon / nvm use ‘lts/*’ / nvm use lts/argon nvm exec -lts / nvm exec
- -lts=argon / nvm exec ‘lts/*’ / nvm exec lts/argon
- nvm
- version-remote lts/argon
run -lts / nvm run -lts=argon / nvm run ‘lts/*’ / nvm run lts/argon nvm ls-remote -lts / nvm ls-remote -lts=argon nvm ls-remote ‘lts/*’ / nvm ls-remote lts/argon nvm version-remote -lts / nvm version-remote -lts=argon / nvm version-remote ‘lts/*’ / nvm
Each time your local copy of nvm connects to https://nodejs.org, it will re-create the appropriate local aliases for all available LTS lines. These aliases (stored in $NVM_DIR/alias/lts) are managed by nvm, and you should not modify, delete, or create these files: expect your changes to be undone, and expect meddling with these files to cause errors that are unlikely to be supported.
To get the latest LTS
version of node and migrate existing installed packages, use Global Package Migration
During Installation
If you want to install a new version of Node.js and migrate npm packages from a previous version:
This will first use “nvm version node” to identify the current version you are migrating packages from. Then, resolve the new version to install from the remote server and install it. Finally, run “nvm reinstall-packages” to reinstall the npm packages from your old version of Node to the new one.
You can also install and migrate npm packages from specific versions of Node like
this: Note that reinstalling packages explicitly does not update the npm version, this is to
ensure that npm is not accidentally upgraded to a corrupted version for the new node version.
To update npm at the same time, add the -latest-npm flag, Like this
: Or, you
can run the following command at any time to get
the latest supported npm version on the current version of the node:
If you have already received an error with the effect of “npm does not support Node.js”, you will need to (1) revert to a previous version of the node (nvm ls & nvm use <your latest _working_ version of the ls>, (2) Delete the newly created node version (nvm uninstall <your _broken_ version of the > node), and then (3) rerun NVM installation with the -latest-npm flag.
Default global
packages from the file during
installation If you have a list of default packages that you want to install every time you install a new version, we also support it: simply add the package names, one per line, to the $NVM_DIR/default-packages file. You can add anything that npm accepts as a packet argument on the command line.
io.js
If you want to install io.js: If you want
to install a new
version of io.js and migrate npm packages from a previous version:
The same guidelines mentioned for migrating npm packages on node are applicable to io.js.
Node system
version
If you want
to use the
version of the node installed on the system, you can use the special default alias “system”:
List
of versions If you want to see which versions are
installed: If you want to see which
versions are available to install:
Setting
custom colors
You can set five colors that will be used to display version and alias information. These colors replace the default colors. The initial colors are: g b and r e Color Codes: Custom Color
Persistence
If you want custom colors to persist after you finish the shell, export the NVM_COLORS variable in the shell profile. For example, if you want to use cyan, magenta, green, bold red, and bold yellow, add the following line:
Colored output suppression
nvm help (or -h or -help), nvm ls, nvm
ls-remote, and nvm alias typically produce colored output. You can disable colors with the -no-colors option (or by setting the environment variable TERM=dumb):
Restoring
PATH To
restore your PATH, you can disable it
: Set the default version of the
node To set a default version of Node for use in any new shell, use the alias ‘default’: Use a node
binary mirror To use
a mirror of node binaries
, set $NVM_NODEJS
_ORG_MIRROR: To use a
mirror of the io.js binaries, set $NVM_IOJS_ORG_MIRROR:
nvm use will not, by default, create a “current” symbolic link. Set $NVM_SYMLINK_CURRENT to “true” to enable this behavior, which is sometimes useful for IDEs. Note that using nvm on multiple shell tabs with this environment variable enabled can cause race conditions.
.nvmrc
You can create an .nvmrc file that contains a node version number (or any other string that nvm understands; see nvm -help for more information) in the root directory of your project (or any parent directory). Subsequently, nvm use, nvm install, nvm exec, nvm run, and nvm that will use the version specified in the .nvmrc file if no version is provided on the command line.
For example, to make nvm default to the latest version 5.9, the latest LTS version, or the latest version of the node for the current directory
:
[Note: These examples assume a POSIX-compliant echo shell version. If you use a Windows cmd development environment, for example, the .nvmrc file is used to configure a remote Linux deployment, note that “it’s will be copied and result in an invalid file. Remove them.]Then, when you run
nvm:
nvm use et. al. it will traverse the directory structure upwards from the current directory looking for the .nvmrc file. In other words, run nvm use et. al. in any subdirectory of a directory with an .nvmrc will result in that .nvmrc being used.
The contents of an .nvmrc file must be the <version> (as described in nvm -help) followed by a new line. No end spaces are allowed and the new end line is required.
Deeper shell integration
You can use avn to integrate deeply into your shell and automatically invoke nvm when changing directories. avn does not support nvm maintainers. Report problems to the avn team.
If you prefer a lighter solution, the following recipes have been contributed by nvm users. They are not supported by nvm maintainers. However, we are accepting pull requests for more examples.
bash
Automatically call using nvm
Put the following at the end of your $HOME/.bashrc:
This alias would look ‘up’ from your current directory to detect an .nvmrc file. If it finds it, it will switch to that version; If not, it will use the default version.
zsh
Call nvm automatically use in a directory with a .
nvmrc
Place this in your $HOME/.zshrc to call the use of nvm automatically whenever you enter a directory containing an .nvmrc file with a string telling nvm which node to use: fish Call nvm use automatically in a directory with a .
nvmrc
This requires you to have bass installed
.
Test Execution
The tests are written in Urchin. Install Urchin (and other dependencies) like this:
There are slow tests and quick tests. Slow testing does things like install the node and verify that the correct versions are used. Quick tests fake this to test things like aliases and uninstallation. From the root of the nvm git repository
, run the quick tests like this: Run the slow tests like this:
Run all the tests like this
:
Nota bene: Avoid
running nvm while
the
tests are running.
NVM Environment Variables
exposes the following environment variables:
- NVM_DIR – NVM installation directory
- npm, and global packages are installed for the active version of the node.
- NVM_INC – node includes file directory (useful for creating C/C++ plugins for node).
- NVM_CD_FLAGS – Used to maintain zsh compatibility.
- NVM_RC_VERSION – version of the .nvmrc file if used.
. NVM_BIN: Where the node,
In addition, nvm
modifies PATH and, if present, MANPATH and NODE_PATH when changing versions
.
Completing Bash
To activate, you must get bash_completion
: Place the above supply line
just below the supply line for nvm in your profile (.bashrc, .bash_profile).
nvm
usage
: $ nvm nvm alias tab: $ nvm alias $ nvm alias
tab $ nvm alias tab my_alias Tab
nvm use:
$ nvm
use
Tab nvm
uninstall:
$ nvm
uninstall Tab
Compatibility Issues
nvm will encounter some issues if you have any non-default settings set. (see #606) The following are known to cause problems
:
Within ~/.npmrc
:
Environment variables: Shell
configuration
:
Installing nvm
on Alpine Linux
In order to provide the best performance (and other optimizations), nvm will download and install precompiled binaries for Node (and npm) when you run nvm install X. The Node project compiles, tests and hosts/provides these precompiled binaries that are built for conventional/traditional Linux distributions (such as Debian, Ubuntu, CentOS, RedHat et al).
Alpine Linux, unlike conventional/traditional Linux distributions, is based on BusyBox, a very compact Linux distribution (~5MB). BusyBox (and therefore Alpine Linux) uses a different C/C++ stack than most conventional/traditional Linux distributions – musl. This makes binary programs built for such mainstream/traditional incompatible with Alpine Linux, so we can’t just install X on Alpine Linux and expect the downloaded binary to run properly, you’re likely to see “… it doesn’t exist” if you try that.
There is a -s flag for the nvm installation that prompts nvm to download the source code from the node and compile it locally.
If installing nvm on Alpine Linux is still what you want or need to do, you should be able to achieve this by running the following from your Alpine Linux shell, depending on the version you are using
: Alpine Linux 3.13+ Alpine Linux 3.5 – 3.12 Note: Alpine 3.5 can only install NodeJS versions up to v6.9.5,
Alpine
3.6 can only install versions up to
v6.10.3
, Alpine 3.7 installs versions up to v8.9.3, Alpine 3.8 installs versions up to v8.14.0, Alpine 3.9 installs versions up to v10.19.0, Alpine 3.10 installs versions up to v10.24.1, Alpine 3.11 installs versions up to v12.22.6, Alpine 3.12 installs versions up to v12.22.12, Alpine 3.13 and 3.14 install versions up to v14.20.0, Alpine 3.15 and 3.16 install versions up to v16.16.0 (These are all versions in the main branch ). Alpine 3.5 – 3.12 required the python2 package to compile NodeJS, as they are older versions to compile. Alpine 3.13+ requires python3 to successfully compile new versions of NodeJS, but you can use python2 with Alpine 3.13+ if you need to create node versions compatible with Alpine 3.5 – 3.15, you just need to specify which version of NodeJS you need to install in the package installation script.
The Node project has some desire, but no concrete plans (due to build, testing, and support overhead) to deliver Alpine-compatible binaries.
As a potential alternative, @mhart (a Node contributor) has some Docker images for Alpine Linux with Node and, optionally, npm, pre-installed.
Manual Uninstallation / Removal Uninstallation
To remove nvm
manually, run
the following:
Edit ~/.bashrc (or other shell resource settings) and delete the following lines:
Docker for development environment To facilitate development and testing work, we have a
Dockerfile for development
use, which is based on the base image of Ubuntu 18.04, prepared with essential and useful tools for
NVM development, To create the Docker image of the environment, run the Docker command at the root of the NVM repository:
This will package your current NVM repository with our predefined development environment in a Docker image called NVM-DEV, once it has been successfully created, validate your image through Docker images
:
If you did not receive any error messages, you can now easily participate in
:
Note that it will take about 8 minutes to build the image and the image size would be about 650 MB, so it is not suitable for production use.
For more information and documentation on docker, see its official website:
- https://www.docker.com/
- https://docs.docker.com/
Problems
-
If you try to install a node version and the installation fails, be sure to run nvm cache clear to remove cached node downloads, or you might get an error like the following
:
curl: (33) The HTTP server does not appear to support byte ranges. Unable to resume.
-
Where is my sudo node? Check out #43
-
After version v0.8.6 of the node, nvm tries to install from binary packages. But on some systems, official binary packages do not work due to incompatibility of shared libraries. In such cases, use the -s option to force installation from
source:
- If the default alias configuration does not set the node version in the new shells (that is, the nvm stream produces the system), ensure that the PATH system node is configured before the source line nvm.sh in your shell profile (see #658) Troubleshooting macOS Version of the nvm node not
found in the
vim shell If you set the node version to a different version than the system node version, nvm use 6.2.1 and open vim and run :!node -v, you should see v6.2.1 if you see system version v0.12.7. You need to run:
More on this topic at dotphiles/dotzsh
.
NVM does not support npm configuration “prefix” option
Some solutions for this problem can be found here
There is one more edge case causing this problem, and it is a mismatch between the $HOME path and the actual name of the user’s home directory. You must ensure that the user directory name in $HOME
and the user directory name you
would see when running ls /Users/ are capitalized in the same way (See this number).
To change the user directory and/or account name, follow the instructions here
Homebrew makes zsh directories unsafe
Homebrew causes unsafe directories
like /usr/local/share/zsh/
site-functions and /usr/local/share/zsh. This isn’t an nvm problem, it’s a homebrew problem. Check here for some solutions related to the problem.
Macs with chip
M1
Added experimental support for M1 architecture in node.js v15.3 and full support in v16.0. Because of this, if you try to install older versions of node as usual, you will probably experience build errors when installing node or out-of-memory errors while running your code.
So, if you want to run a version earlier than v16.0 on an M1 Mac, it may be best to compile the node targeting Intel x86_64 architecture so that Rosetta 2 can translate x86_64 processor instructions to ARM-based Apple Silicon instructions. Here’s what you’ll need to do:
-
Install Rosetta, if you haven’t already You
might be wondering, “How will my Mac M1 know to use Rosetta for a node version compiled for an Intel chip?” If an executable contains only Intel instructions, macOS will automatically use Rosetta to translate the instructions.
-
a shell that is running with Rosetta
Note:
The same can also be accomplished by searching for the Terminal or iTerm application in the Finder, right-clicking, selecting “Get Info,” and then checking the box labeled “Open using Rosetta.” Note
: This terminal session is now running on zsh. If zsh is not the shell you normally use, nvm may not be automatically sourced as it probably is for your regular shell through your dotfiles. If that’s the case, make sure you get nvm.
-
Install any previous version of the node that you are interested in. Let’s use 12.22.1 as an example. This will find the source code of the node and compile it, which will take several minutes.
Note: You’re probably curious why -shared-zlib is included. There is a bug in recent versions of Apple’s system clang compiler. If one of these broken versions is installed on your system, chances are the previous step will still succeed even if you didn’t include the -shared-zlib brand. However, later on, when you try to install npm something using your older version of node.js, you will see incorrect data verification errors. If you want to avoid the potential hassle of dealing with this, include that flag. For more details, see this issue and this Revert
-
to your native shell
comment.
Note: If you selected the “Open using Rosetta” checkbox instead of running the CLI command in the second step, you will see i386 here. Unless you have another reason for selecting that checkbox, you can deselect it now.
-
Verify that the architecture is correct. x64 is short for x86_64, which is what you want to see.
Open
You should now be able to use the node as usual.
Troubleshooting WSL
If you have encountered this error in WSL-2
:
It may be due to your antivirus, VPN, or other reasons
. Where you can ping 8.8.8.8
while you can’t ping google.com
This
could be solved by simply running this in your root directory: This deletes your
resolve.conf file that is automatically generated when you run
WSL
, creates a new file and
puts nameserver 8.8.8.8, then creates a wsl.conf file and adds [network] and generateResolveConf=false to prevent automatic generation of that file.
You can check the contents of the file by running:
Maintainers
Currently, the
only maintainer is @ljharb – more maintainers are welcome, and we hope to add people to the team over time. Governance will be reassessed as the project evolves.
License
See LICENSE.md
.
Copyright
Notice Copyright OpenJS Foundation and nvm contributors. All rights reserved. The OpenJS Foundation has registered trademarks and uses trademarks. For a list of OpenJS Foundation trademarks, please see our Trademark Policy and Trademark List. Node.js is a trademark of Joyent, Inc. and is used with permission. Trademarks and logos not indicated in the OpenJS Foundation trademark list are™ trademarks or registered® trademarks of their respective owners. The use of them does not imply any affiliation or endorsement by them.
The OpenJS Foundation | Terms of Use | Privacy Policy | Statutes of the OpenJS Foundation | Trademark Policy | List of Brands | Cookies policy