Seamlessly manage your app’s Node environment with nodenv

nodenv is a version manager tool for the Node.js on Unix-like systems. It is useful for switching between multiple Node.js versions on the same machine and for ensuring that each project you are working on always runs on the correct Node.js version.

After nodenv injects itself into your PATH at installation time, any invocation of node, npm, npx, or other Node.js-related executable will first activate nodenv. Then, nodenv scans the current project directory for a file named .node-version. If found, that file determines the version of Node.js that should be used within that directory. Finally, nodenv looks up that Node.js version among those installed under ~/.nodenv/versions/.

You can choose the Node.js version for your project with, for example:

cd myproject
# choose Node.js version 24.1.0:
nodenv local 24.1.0

Doing so will create or update the .node-version file in the current directory with the version that you've chosen. A different project of yours that is another directory might be using a different version of Node.js altogether—nodenv will seamlessly transition from one Node.js version to another when you switch projects.

Finally, almost every aspect of nodenv's mechanism is customizable via plugins written in Bash.

The simplicity of nodenv has its benefits, but also some downsides. See the comparison of version managers for more details and some alternatives.

On systems with Homebrew package manager, the “Using Package Managers” method is recommended. On other systems, “Basic Git Checkout” might be the easiest way of ensuring that you are always installing the latest version of nodenv.

1. Install nodenv using one of the following approaches.

   Homebrew

   On macOS or Linux, we recommend installing nodenv with Homebrew.

   brew install nodenv

   Debian, Ubuntu, and their derivatives

   [!CAUTION] Presently, nodenv is not available in the Debian or Ubuntu package repositories. To install the latest version, it is recommended to install nodenv using Git. Consider contributing!

   Arch Linux and its derivatives

   Archlinux has an AUR Package for nodenv and you can install it from the AUR using the instructions from this wiki page.

   Fedora

   [!CAUTION] Presently, nodenv is not available in the Fedora package repositories. To install the latest version, it is recommended to install nodenv using Git. Consider contributing!

2. Set up your shell to load nodenv.

   nodenv init

3. Close your Terminal window and open a new one so your changes take effect.

That's it! You are now ready to install some Node.js versions.

This will get you going with the latest version of nodenv without needing a system-wide install.

1. Clone nodenv into ~/.nodenv.

   git clone https://github.com/nodenv/nodenv.git ~/.nodenv

2. Set up your shell to load nodenv.

   ~/.nodenv/bin/nodenv init

   • For Fish shell:

     echo 'status --is-interactive; and ~/.nodenv/bin/nodenv init - fish | source' >> ~/.config/fish/config.fish

   If you are curious, see here to understand what init does.

3. Restart your shell so that these changes take effect. (Opening a new terminal tab will usually do it.)

When manually installing nodenv, it might be useful to note how completion scripts for various shells work. Completion scripts help with typing nodenv commands by expanding partially entered nodenv command names and option flags; typically this is invoked by pressing Tab key in an interactive shell.

• The Bash completion script for nodenv ships with the project and gets loaded by the nodenv init mechanism.

• The Zsh completion script ships with the project, but needs to be added to FPATH in Zsh before it can be discovered by the shell. One way to do this would be to edit ~/.zshrc:

  # assuming that nodenv was installed to `~/.nodenv`
  FPATH=~/.nodenv/completions:"$FPATH"
  
  autoload -U compinit
  compinit

• The fish completion script for nodenv ships with the project and gets loaded by the nodenv init mechanism.

The nodenv install command does not ship with nodenv out-of-the-box, but is provided by the node-build plugin.

Before attempting to install Node.js, check that your build environment has the necessary tools and libraries. Then:

# list latest stable versions:
nodenv install -l

# list all local versions:
nodenv install -L

# install a Node.js version:
nodenv install 24.1.0

git clone https://github.com/nodenv/node-build.git "$(nodenv root)"/plugins/node-build

Set a Node.js version to finish installation and start using Node.js:

nodenv global 24.1.0   # set the default Node.js version for this machine
# or:
nodenv local 24.1.0    # set the Node.js version for this directory

Alternatively to the nodenv install command, you can download and compile Node.js manually as a subdirectory of ~/.nodenv/versions. An entry in that directory can also be a symlink to a Node.js version installed elsewhere on the filesystem.

Select a Node.js version for your project using nodenv local 24.1.0, for example. Then, proceed to install packages as you normally would:

npm install testdouble

Packages installed globally are scoped to the currently-active Node.js version. If there is a set of npm packages that you wish to be installed (globally) in every Node.js version, you may be interested in the nodenv-default-packages plugin.

Check the location where packages are being installed with npm prefix -g:

$ npm prefix -g
~/.nodenv/versions/<version>

As time goes on, Node.js versions you install will accumulate in your ~/.nodenv/versions directory.

To remove old Node.js versions, simply rm -rf the directory of the version you want to remove. You can find the directory of a particular Node.js version with the nodenv prefix command, e.g. nodenv prefix 20.7.0.

The node-build plugin provides an nodenv uninstall command to automate the removal process.

The main nodenv commands you need to know are:

Lists all Node.js versions known to nodenv, and shows an asterisk next to the currently active version.

$ nodenv versions
  20.19.4
  22.17.1
* 24.4.1 (set by /Users/jasonkarns/code/testdouble/.node-version)
  graal+ce-19.2.1
  iojs-3.3.1

Displays the currently active Node.js version, along with information on how it was set.

$ nodenv version
24.4.1 (set by /Users/jasonkarns/code/testdouble/.node-version)

Sets a local application-specific Node version by writing the version name to a .node-version file in the current directory. This version overrides the global version, and can be overridden itself by setting the NODENV_VERSION environment variable or with the nodenv shell command.

nodenv local 24.1.0

When run without a version number, nodenv local reports the currently configured local version. You can also unset the local version:

nodenv local --unset

Sets the global version of Node to be used in all shells by writing the version name to the ~/.nodenv/version file. This version can be overridden by an application-specific .node-version file, or by setting the NODENV_VERSION environment variable.

nodenv global 24.1.0

The special version name system tells nodenv to use the system Node (detected by searching your $PATH).

When run without a version number, nodenv global reports the currently configured global version.

Sets a shell-specific Node version by setting the NODENV_VERSION environment variable in your shell. This version overrides application-specific versions and the global version.

nodenv shell 20.7.0

When run without a version number, nodenv shell reports the current value of NODENV_VERSION. You can also unset the shell version:

nodenv shell --unset

Note that you'll need nodenv's shell integration enabled (step 3 of the installation instructions) in order to use this command. If you prefer not to use shell integration, you may simply set the NODENV_VERSION variable yourself:

export NODENV_VERSION=20.7.0

Installs shims for all Node.js executables known to nodenv (~/.nodenv/versions/*/bin/*). You may need to run this command after installing/uninstalling packages. Or see the nodenv-package-rehash plugin.

nodenv rehash

Displays the full path to the executable that nodenv will invoke when you run the given command.

$ nodenv which npm
/Users/will/.nodenv/versions/24.1.0/bin/npm

Lists all Node.js versions that contain the specified executable name.

$ nodenv whence yarn
24.1.0
20.7.0

You can affect how nodenv operates with the following settings:

nodenv init is a helper command to hook nodenv into a shell. This helper is part of the recommended installation instructions, but optional, as an experienced user can set up the following tasks manually. The nodenv init command has two modes of operation:

1. nodenv init: made for humans, this command edits your shell initialization files on disk to add nodenv to shell startup. (Prior to nodenv 1.6.0, this mode only printed user instructions to the terminal, but did nothing else.)

2. nodenv init -: made for machines, this command outputs a shell script suitable to be eval'd by the user's shell.

When nodenv init is invoked from a Bash shell, for example, it will add the following to the user's ~/.bashrc or ~/.bash_profile:

# Added by `nodenv init` on <DATE>
eval "$(nodenv init - --no-rehash bash)"

You may add this line to your shell initialization files manually if you want to avoid running nodenv init as part of the setup process. Here is what the eval'd script does:

0. Adds nodenv executable to PATH if necessary.

1. Prepends ~/.nodenv/shims directory to PATH. This is basically the only requirement for nodenv to function properly.

2. Installs Bash shell completion for nodenv commands.

3. Regenerates nodenv shims. If this step slows down your shell startup, you can invoke nodenv init - with the --no-rehash flag.

4. Installs the "sh" dispatcher. This bit is also optional, but allows nodenv and plugins to change variables in your current shell, making commands like nodenv shell possible.

The simplicity of nodenv makes it easy to temporarily disable it, or uninstall from the system.

1. To disable nodenv managing your Node.js versions, simply comment or remove the nodenv init line from your shell startup configuration. This will remove nodenv shims directory from PATH, and future invocations like node will execute the system Node.js version, bypassing nodenv completely.

   While disabled, nodenv will still be accessible on the command line, but your Node.js apps won't be affected by version switching.

2. To completely uninstall nodenv, perform step (1) and then remove the nodenv root directory. This will delete all Node.js versions that were installed under `nodenv root`/versions/:

   rm -rf "$(nodenv root)"

   If you've installed nodenv using a package manager, as a final step perform the nodenv package removal:

   • Homebrew: brew uninstall nodenv
   • Debian, Ubuntu, and their derivatives: sudo apt purge nodenv
   • Archlinux and its derivatives: sudo pacman -R nodenv

Tests are executed using Bats:

npm test
bats test/<file>.bats

Please feel free to submit pull requests and file bugs on the issue tracker.

Forked from Sam Stephenson's rbenv by Will McKenzie and modified for Node.js.