n/README.md

# `n` – Interactively Manage Your Node.js Versions

[![npm](https://img.shields.io/npm/dt/n.svg?style=flat-square)](https://www.npmjs.com/package/n)
[![npm](https://img.shields.io/npm/dm/n.svg?style=flat-square)](https://www.npmjs.com/package/n)
[![npm](https://img.shields.io/npm/v/n.svg?style=flat-square)](https://www.npmjs.com/package/n)
[![npm](https://img.shields.io/npm/l/n.svg?style=flat-square)](https://www.npmjs.com/package/n)

Node.js version management: no subshells, no profile setup, no convoluted API, just **simple**.

![usage animation](http://nimit.io/images/n/n.gif)

(Note: `n` is not supported natively on Windows.)

- [`n` – Interactively Manage Your Node.js Versions](#n-%E2%80%93-interactively-manage-your-nodejs-versions)
    - [Installation](#installation)
        - [Third Party Installers](#third-party-installers)
    - [Installing/Activating Node Versions](#installingactivating-node-versions)
    - [Removing Versions](#removing-versions)
    - [Binary Usage](#binary-usage)
    - [Usage](#usage)
    - [Custom source](#custom-source)
    - [Custom architecture](#custom-architecture)
    - [Additional Details](#additional-details)

## Installation

Since you probably already have `node`, the easiest way to install `n` is through `npm`:

    npm install -g n

Alternatively, you can clone this repo and

    make install

to install `n` to `bin/n` of the directory specified in the environment variable `$PREFIX`, which defaults to `/usr/local` (note that you will likely need to use `sudo`). To install `n` in a custom location (such as `$CUSTOM_LOCATION/bin/n`), run `PREFIX=$CUSTOM_LOCATION make install`.

Once installed, `n` installs `node` versions to subdirectory `n/versions` of the directory specified in environment variable `N_PREFIX`, which defaults to `/usr/local`; the _active_ `node` version is installed directly in `N_PREFIX`.
To change the default to, say, `$HOME`, prefix later calls to `n` with `N_PREFIX=$HOME` or add `export N_PREFIX=$HOME` to your shell initialization file.

To avoid requiring `sudo` for `n` and `npm` global installs, it is recommended you either install to your home directory using `N_PREFIX`, or take ownership of the system directories:

```bash
# make cache folder (if missing) and take ownership
sudo mkdir -p /usr/local/n
sudo chown -R $(whoami) /usr/local/n
# take ownership of node install destination folders
sudo chown -R $(whoami) /usr/local/bin /usr/local/lib /usr/local/include /usr/local/share
```

### Third Party Installers

On macOS with [Homebrew](https://brew.sh/) you can install the [n formula](https://github.com/Homebrew/homebrew-core/blob/master/Formula/n.rb).

    brew install n

On Linux and macOS, [n-install](https://github.com/mklement0/n-install) allows installation directly from GitHub; for instance:

    curl -L https://git.io/n-install | bash

n-install sets both `PREFIX` and `N_PREFIX` to `$HOME/n`, installs `n` to `$HOME/n/bin`, modifies the initialization files of supported shells to export `N_PREFIX` and add `$HOME/n/bin` to the `PATH`, and installs the latest stable `node` version.

As a result, both `n` itself and all `node` versions it manages are hosted inside a single, optionally configurable directory, which you can later remove with the included `n-uninstall` script. `n-update` updates `n` itself to the latest version. See the [n-install repo](https://github.com/mklement0/n-install) for more details.

## Installing/Activating Node Versions

Simply execute `n <version>` to install a version of `node`. If `<version>` has already been installed (via `n`), `n` will activate that version.
A leading v is optional, and a partial version number installs the newest matching version.

    n 4.9.1
    n 10
    n v8.11.3

Execute `n` on its own to view your currently installed versions. Use the up and down arrow keys to navigate and press enter to select. Use `q` or ^C (control + C) to exit the selection screen.
If you like vim key bindings during the selection of node versions, you can use `j` and `k` to navigate up or down without using arrows.

    $ n

      node/4.9.1
    ο node/8.11.3
      node/10.15.0

Use or install the latest official release:

    n latest

Use or install the latest LTS official release:

    n lts

## Removing Versions

Remove some versions:

    n rm 0.9.4 v0.10.0

Removing all versions except the current version:

    n prune

## Binary Usage

When running multiple versions of `node`, we can target
them directly by asking `n` for the binary path:

    $ n bin 0.9.4
    /usr/local/n/versions/0.9.4/bin/node

Or by using a specific version through `n`'s `use` sub-command:

    n use 0.9.4 some.js

Flags also work here:

    n as 0.9.4 --debug some.js

## Usage

Output can also be obtained from `n --help`.

    Usage: n [options/env] [COMMAND] [args]

    Environments:
     n [COMMAND] [args]            Uses default env (node)

    Commands:

      n                              Output versions installed
      n latest                       Install or activate the latest node release
      n -a x86 latest                As above but force 32 bit architecture
      n lts                          Install or activate the latest LTS node release
      n <version>                    Install node <version>
      n use <version> [args ...]     Execute node <version> with [args ...]
      n bin <version>                Output bin path for <version>
      n rm <version ...>             Remove the given version(s)
      n prune                        Remove all versions except the current version
      n --latest                     Output the latest node version available
      n --lts                        Output the latest LTS node version available
      n ls                           Output the versions of node available

    Options:

      -V, --version   Output current version of n
      -h, --help      Display help information
      -q, --quiet     Disable curl output (if available)
      -d, --download  Download only
      -a, --arch      Override system architecture

    Aliases:

      which   bin
      use     as
      list    ls
      -       rm
      stable  lts

## Custom source

If you would like to use a project other than the official Node.js project, you can use the special `n project [command]` which allows you to control the behavior of `n` using environment variables.

For example, to grab the latest io.js version:

      PROJECT_NAME="iojs" PROJECT_URL="https://iojs.org/dist/" n project latest

Required Variables:

- `PROJECT_NAME`: The name the project will be stored under
- `PROJECT_URL`: The location to download the project from. Note, this must follow the same format as the Node.js repos

Optional Variables:

- `HTTP_USER`: The username if the `PROJECT_URL` is protected by basic authentication
- `HTTP_PASSWORD`: The password if the `PROJECT_URL` is protected by basic authentication
- `PROJECT_VERSION_CHECK`: Many custom projects keep the same version number as the Node.js release they are based on, and maintain their own separate version in process. This allows you to define a JavaScript variable that will be used to check for the version of the process, for example: `process.versions.node`

## Custom architecture

By default `n` picks the binaries matching your system architecture, e.g. `n` will download 64 bit binaries for a 64 bit system. You can override this by using the `-a` or `--arch` option.

Download and use latest 32 bit version of `node`:

    n --arch x86 latest

Download and use 64 bit LTS version of `node` for older Mac Intel Core 2 Duo systems (x86 image is no longer available but x64 runs fine):

    n --arch x64 lts

## Additional Details

`n` installs versions to `/usr/local/n/versions` by default. Here, it can see what versions are currently installed and activate previously installed versions accordingly when `n <version>` is invoked again.

Activated versions are then installed to the prefix `/usr/local`, which may be altered via the __`N_PREFIX`__ environment variable.

To alter where `n` operates, simply `export N_PREFIX`.