If you’re looking for an easy to follow guide to install Node.js and npm on OS X, the default method is to download a pre-built installer for your platform, install it, and make sure it’s on your $PATH.

As of July 21st, 2017 this guide is deprecated.

But, if you’re a Homebrew fan like me and prefer to install all of your packages with it, ensuring your packages are installed using the same commands and directories and allowing Homebrew to manage updates, this guide will help you get started:

Install Node.js and npm with Homebrew

First, install Homebrew: (If you wan’t to install it the right way, here’s how to do it!)

Note: The best way to install Homebrew is to get the link directly from their website. (It can change over time)

Then, brew update to ensure your Homebrew is up to date.

brew update

As a safe measure, run brew doctor to make sure your system is ready to brew. Follow any recommendations from brew doctor.

brew doctor

Next, if you haven’t already add the Homebrew location to your $PATH and source your bash or zsh profile file after adding/saving this:

export PATH="/usr/local/bin:$PATH"

Next, install Node (npm will be installed with node):

brew install node

To test out your Node and npm install, try installing Grunt (you might be asked to run with sudo):

npm install grunt-cli -g

If that worked, congrats, you’re good to go with Node.js, npm, and Grunt. If not, the following are a few troubleshooting steps:

If you see an error like this:

$ npm update npm -g
npm http GET https://registry.npmjs.org/npm
npm http 304 https://registry.npmjs.org/npm
npm http GET https://registry.npmjs.org/npm/1.4.4
npm http 304 https://registry.npmjs.org/npm/1.4.4
npm ERR! error rolling back Error: Refusing to delete: /usr/local/bin/npm not in /usr/local/lib/node_modules/npm
npm ERR! error rolling back     at clobberFail (/usr/local/Cellar/node/0.10.26/lib/node_modules/npm/lib/utils/gently-rm.js:57:12)
npm ERR! error rolling back     at next (/usr/local/Cellar/node/0.10.26/lib/node_modules/npm/lib/utils/gently-rm.js:43:14)
npm ERR! error rolling back     at /usr/local/Cellar/node/0.10.26/lib/node_modules/npm/lib/utils/gently-rm.js:52:12
npm ERR! error rolling back     at Object.oncomplete (fs.js:107:15)
npm ERR! error rolling back  npm@1.4.4 { [Error: Refusing to delete: /usr/local/bin/npm not in /usr/local/lib/node_modules/npm] code: 'EEXIST', path: '/usr/local/bin/npm' }
npm ERR! Refusing to delete: /usr/local/bin/npm not in /usr/local/lib/node_modules/npm
File exists: /usr/local/bin/npm
Move it away, and try again. 

npm ERR! System Darwin 13.1.0
npm ERR! command "/usr/local/Cellar/node/0.10.26/bin/node" "/usr/local/bin/npm" "update" "npm" "-g"
npm ERR! cwd /Users/dan/Google Drive/Projects/dotfiles
npm ERR! node -v v0.10.26
npm ERR! npm -v 1.4.3
npm ERR! path /usr/local/bin/npm
npm ERR! code EEXIST
npm ERR! 
npm ERR! Additional logging details can be found in:
npm ERR!     /Users/dan/Google Drive/Projects/dotfiles/npm-debug.log
npm ERR! not ok code 0

Run! Ha.

Explanation of the issue

There’s an npm bug for this exact problem. The bug has been “fixed” by Homebrew installing npm in a way that allows it to manage itself once the install is complete. However, this is error-prone and still seems to cause problems for some people. The root of the the issue is really that npm is its own package manager and it is therefore better to have npm manage itself and its packages completely on its own instead of letting Homebrew do it.

Also, using the Homebrew installation of npm will require you to use sudo when installing global packages. Since one of the core ideas behind Homebrew is that apps can be installed without giving them root access, this is a bad idea.

Solution

This solution fixes the error caused by trying to run npm update npm -g. Once you’re finished, you also won’t need to use sudo to install npm modules globally.

Before you start, make a note of any globally installed npm packages. These instructions will have you remove all of those packages. After you’re finished you’ll need to re-install them.

Run the following commands to remove all existing global npm modules, uninstall node & npm, re-install node with the right defaults, install npm as its own pacakge, and configure the location for global npm modules to be installed.

rm -rf /usr/local/lib/node_modules
brew uninstall node
brew install node --without-npm
echo prefix=~/.node >> ~/.npmrc
curl -L https://www.npmjs.com/install.sh | sh

Node and npm should be correctly installed at this point. The final step is to add ~/.node/bin to your PATH so commands you install globally are usable. I added this line to my ~/.path script, which gets run via ~/.bash_profile.

export PATH="$HOME/.node/bin:$PATH"

Now you can re-install any global packages with the command below, replacing the npm modules with whatever global packages you need.

npm install -g http-server node-inspector forever nodemon

If you need to install multiple versions of node, do yourself a favor and use nvm. It helps you manage node versions and you won’t need root privileges (sudo command) to use it.

Install nvm:

brew install nvm

Add the following to your $PATH and source your bash or zsh profile file:

export NVM_DIR=$(brew --prefix)/var/nvm
source $(brew --prefix nvm)/nvm.sh

The first line tells nvm where to install versions of node. Since you are already using brew to manage these binaries, it makes sense to use that directory.

Now use nvm to install the latest stable release of node, and the most up to date version in the branch for all your older node packages.

nvm install stable
nvm install [Latest Version]

If you need to install io.js you can do it safely along with node.js:

brew update
brew upgrade nvm
nvm install iojs

Don’t be lazy and read some nvm documentation. Cheers!