Groom your app’s Node environment with nenv.
Use nenv to pick a Node.js / io.js version for your application and guarantee that your development environment matches production. Put nenv to work with npm for painless Node upgrades and bulletproof deployments.
Table of Contents
- How It Works
- Command Reference
- Environment variables
How It Works
At a high level, nenv intercepts Node commands using shim
executables injected into your
PATH, determines which Node version
has been specified by your application, and passes your commands along
to the correct Node installation.
When you run a command like
gulp, your operating system
searches through a list of directories to find an executable file with
that name. This list of directories lives in an environment variable
PATH, with each directory in the list separated by a colon:
PATH are searched from left to right, so a matching
executable in a directory at the beginning of the list takes
precedence over another one at the end. In this example, the
/usr/local/bin directory will be searched first, then
nenv works by inserting a directory of shims at the front of your
Through a process called rehashing, nenv maintains shims in that
directory to match every Node command across every installed version
gulp and so on.
Shims are lightweight executables that simply pass your command along
to nenv. So with nenv installed, when you run, say,
operating system will do the following:
- Search your
PATHfor an executable file named
- Find the nenv shim named
gulpat the beginning of your
- Run the shim named
gulp, which in turn passes the command along to nenv
Choosing the Node Version
When you execute a shim, nenv determines which Node version to use by reading it from the following sources, in this order:
NENV_VERSIONenvironment variable, if specified. You can use the
nenv shellcommand to set this environment variable in your current shell session.
.node-versionfile found by searching the directory of the script you are executing and each of its parent directories until reaching the root of your filesystem.
.node-versionfile found by searching the current working directory and each of its parent directories until reaching the root of your filesystem. You can modify the
.node-versionfile in the current working directory with the
~/.nenv/versionfile. You can modify this file using the
nenv globalcommand. If the global version file is not present, nenv assumes you want to use the "system" Node—i.e. whatever version would be run if nenv weren't in your path.
Locating the Node Installation
Once nenv has determined which version of Node your application has specified, it passes the command along to the corresponding Node installation.
Each Node version is installed into its own directory under
~/.nenv/versions. For example, you might have these versions
Version names to nenv are simply the names of the directories in
Basic GitHub Checkout
This will get you going with the latest version of nenv and make it easy to fork and contribute any changes back upstream.
Check out nenv into
$ git clone https://github.com/ryuone/nenv.git ~/.nenv
$PATHfor access to the
$ echo 'export PATH="$HOME/.nenv/bin:$PATH"' >> ~/.bash_profile
Ubuntu Desktop note: Modify your
Zsh note: Modify your
~/.zshrcfile instead of
nenv initto your shell to enable shims and autocompletion.
$ echo 'eval "$(nenv init -)"' >> ~/.bash_profile
Same as in previous step, use
~/.bashrcon Ubuntu, or
Restart your shell so that PATH changes take effect. (Opening a new terminal tab will usually do it.) Now check if nenv was set up:
$ nenv versions #=> "system"
If you've installed nenv manually using git, you can upgrade your installation to the cutting-edge version at any time.
$ cd ~/.nenv $ git pull
To use a specific release of nenv, check out the corresponding tag:
$ cd ~/.nenv $ git fetch $ git checkout v0.0.6
How nenv hooks into your shell
Skip this section unless you must know what every line in your shell profile is doing.
nenv init is the only command that crosses the line of loading
extra commands into your shell. Coming from RVM, some of you might be
opposed to this idea. Here's what
nenv init actually does:
Sets up your shims path. This is the only requirement for nenv to function properly. You can do this by hand by prepending
Installs autocompletion. This is entirely optional but pretty useful. Sourcing
~/.nenv/completions/nenv.bashwill set that up. There is also a
~/.nenv/completions/nenv.zshfor Zsh users.
Rehashes shims. From time to time you'll need to rebuild your shim files. Doing this automatically makes sure everything is up to date. You can always run
Installs the sh dispatcher. This bit is also optional, but allows nenv and plugins to change variables in your current shell, making commands like
nenv shellpossible. The sh dispatcher doesn't do anything crazy like override
cdor hack your shell prompt, but if for some reason you need
nenvto be a real script rather than a shell function, you can safely skip it.
nenv init - for yourself to see exactly what happens under the
Installing Node Versions
# list all available versions: $ nenv install -l # install a Node version: $ nenv install 3.2.0
Alternatively to the
install command, you can download and compile
Node manually as a subdirectory of
~/.nenv/versions/. An entry in
that directory can also be a symlink to a Node version installed
elsewhere on the filesystem. nenv doesn't care; it will simply treat
any entry in the
versions/ directory as a separate Node version.
Uninstalling Node Versions
As time goes on, Node versions you install will accumulate in your
To remove old Node versions, simply
rm -rf the directory of the
version you want to remove. You can find the directory of a particular
Node version with the
nenv prefix command, e.g.
nenv prefix 3.2.0.
You can also run the
nenv uninstall command to
automate the removal process.
The simplicity of nenv makes it easy to temporarily disable it, or uninstall from the system.
- To disable nenv managing your Node versions, simply remove the
nenv initline from your shell startup configuration. This will remove nenv shims directory from PATH, and future invocations like
nodewill execute the system Node version, as before nenv.
nenv will still be accessible on the command line, but your Node
apps won't be affected by version switching.
To completely uninstall nenv, perform step (1) and then remove its root directory. This will delete all Node versions that were installed under
rm -rf `nenv root`
If you've installed nenv using a package manager, as a final step perform the nenv package removal. For instance, for Homebrew:
brew uninstall nenv
nenv command delegates to subcommands based on its
first argument. The most common subcommands are:
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
NENV_VERSION environment variable or with the
$ nenv local 3.2.0
When run without a version number,
nenv local reports the currently
configured local version. You can also unset the local version:
$ nenv local --unset
Previous versions of nenv stored local version specifications in a
.nenv-version. For backwards compatibility, nenv will
read a local version specified in an
.nenv-version file, but a
.node-version file in the same directory will take precedence.
Sets the global version of Node to be used in all shells by writing
the version name to the
~/.nenv/version file. This version can be
overridden by an application-specific
.node-version file, or by
NENV_VERSION environment variable.
$ nenv global 3.2.0
The special version name
system tells nenv to use the system Node
(detected by searching your
When run without a version number,
nenv global reports the
currently configured global version.
Sets a shell-specific Node version by setting the
environment variable in your shell. This version overrides
application-specific versions and the global version.
$ nenv shell 3.2.0
When run without a version number,
nenv shell reports the current
NENV_VERSION. You can also unset the shell version:
$ nenv shell --unset
Note that you'll need nenv'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
NENV_VERSION variable yourself:
$ export NENV_VERSION=3.2.0
Lists all Node versions known to nenv, and shows an asterisk next to the currently active version.
$ nenv versions system 0.12.4 * 3.2.0 (set by /home/madumlao/.nenv/version)
Displays the currently active Node version, along with information on how it was set.
$ nenv version 3.2.0 (set by /home/madumlao/.nenv/version)
Installs shims for all Node executables known to nenv (i.e.,
~/.nenv/versions/*/bin/*). Run this command after you install a new
version of Node, or install a gem that provides commands.
$ nenv rehash
Displays the full path to the executable that nenv will invoke when you run the given command.
$ nenv which node /home/madumlao/.nenv/versions/3.2.0/bin/node
Lists all Node versions with the given command installed.
$ nenv whence gulp 0.12.4 3.2.0
You can affect how nenv operates with the following settings:
||Specifies the Node version to be used.
||Defines the directory under which Node versions and shims reside.
||Outputs debug information.
||[see wiki][hooks]||Colon-separated list of paths searched for nenv hooks.|
||Directory to start searching for
The nenv source code is hosted on GitHub. Help us maintain it!
nenv heavily inspired by rbenv. Please refer to rbenv for architecture and inspiration.