NPM Fix for Homebrew Users on macOS

With the initial npm 5 release a few months ago, I immediately noticed a few issues with my local dev-setup. I’m a Homebrew user and I install node.js without npm. With the latest release of node: 8.4.0 and npm: 5.4.0, installing node through Homebrew can cause problems for globally installed packages. To properly fix this, use the steps below.

Note: I did contact npm support through e-mail in late May, 2017, their response time was amazing. However, their support was disappointing! Due to not finding a fix I was forced to use yarn for two months; ha.

The following steps will fix the error:

npm: command not found

Before we begin, make a note of any globally installed npm packages. This guide will have you remove all of those packages. At the end of the guide you’ll need to re-install them. Also, once you’re finished, you won’t need to use sudo to install npm modules globally.

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

1. Re-install node without npm

# run the following commands

# this next line removes all the existing global npm packages
rm -rf /usr/local/lib/node_modules

# remove previously installed node
brew uninstall node
# clean all broken symlinks
brew prune
# always a good idea to have the latest version of Homebrew
brew update

# install node via Homebrew, but without npm
# there are two options:
# - if you want to use `yarn` (yarnpkg.com), you need latest 'node'
# - if you don't use `yarn` (yarnpkg.com), prefer LTS 'node@6'

brew install node --without-npm

# this next step is optional
# install yarn (see yarnpkg.com for more info)
brew install yarn
# follow up with: https://yarnpkg.com/en/docs/install

Just for fun, run:

node --version

Output should be:

v8.4.0

2. Setup npm new home: /user/local/npm_packages

# run the following commands

mkdir -p /usr/local/npm_packages

# USE ONLY IF THE ABOVE COMMAND FAILS >>>
# it means the permissions are wrong with your `/usr/local` folder, so fix it;
# normally, with Homebrew, your user should own the entire `/usr/local` folder:

sudo chown -R `whoami` /usr/local

For bash users: add/append the following lines in ~/.bashrc

# this is the root folder where all globally installed node packages will go
export NPM_PACKAGES="/usr/local/npm_packages"
export NODE_PATH="$NPM_PACKAGES/lib/node_modules:$NODE_PATH"
# add to PATH
export PATH="$NPM_PACKAGES/bin:$PATH"

Make sure you load the .bashrc in your .bash_profile

IMPORTANT: Please make sure you don’t have both a .profile and a .bash_profile; if you do, copy everything from .profile into .bash_profile and then remove the .profile
Check if the following line exists in your .bash_profile:

[[ -s ~/.bashrc ]] && source ~/.bashrc

make sure .bashrc is executable

# run the following command

chmod +x ~/.bashrc

At this point go ahead and restart iTerm/Terminal

Please note: It is wise to close all existing iTerm/Terminal sessions and re-open iTerm/Terminal.

Advanced users; ha. Reload the .bash_profile:

source ~/.bash_profile

For zsh users: add/append the following lines in ~/.zshrc

# npm
export NPM_PACKAGES="/usr/local/npm_packages"
export NODE_PATH="$NPM_PACKAGES/lib/node_modules:$NODE_PATH"
export PATH="$NPM_PACKAGES/bin:$PATH"

You can either close iTerm/Terminal or reload .zshrc:

source ~/.zshrc

3. Install npm directly from npmjs.com

Let’s go ahead and set the correct home in ~/.npmrc

Note: If the ~/.npmrc file does not exist, create one.

Open ~/.npmrc with your favorite text editor and make sure it has the following line:

prefix=/usr/local/npm_packages

Now, let’s run the npm install script from npmjs.com

Note: curl -L https://www.npmjs.com/install.sh | sh silently fails and doesn’t copy the npm package contents correctly. In order to fix this, let’s do the falling after running the npm install.sh script.

curl -L https://www.npmjs.com/install.sh | sh

You may receive a failed message, do not worry let’s fix it:

# manually download and un-targz into a local directory (it will be named `package`)
curl -L https://registry.npmjs.org/npm/-/npm-5.3.0.tgz | tar xz

# remove the broken npm symlink (generated by the nppmjs install.sh script)
rm -rf /usr/local/npm_packages/lib/node_modules/npm

# move the extracted `package` in the correct place and rename to `npm`
mv package /usr/local/npm_packages/lib/node_modules/npm

# that should do it. The bin/npm symlinks should now work

# make sure it works, and update to latest available npm:
npm install -g npm@latest

# if you reach this step, w/o any errors =>  ALL OK!

That’s it. You should now be able to run the npm command without sudo.

A huge shoutout to Radu Cugut for providing this fix, go follow him already @rcugut

Happy coding!

OceanLab

Fixing npm on macOS for Homebrew Users