Npm Debugging Guidelines (Failed npm install, bower install, or gulp build? Read this)


Sage is tested on Travis CI with every commit to make sure that npm install, bower install, and gulp all work properly. Bugs can still pop up, but usually there’s something wrong with your environment if you can’t get things running.

If you’re running into problems, first make sure that your development environment meets the minimum requirements:

  • Node.js >= 4.5.0
  • gulp >= 3.8.10
  • Bower >= 1.3.12

Ensure you’re using the latest version of npm: npm install -g npm@latest

Then run npm cache clear && rm -rf node_modules && npm install from your theme directory. You might want to run it and make a note of the errors you’re getting, if any.

Let us know what versions of things you’re running by typing node -v && npm -v && gulp -v

How to start for a newbie
Error when running gulp
Npm install multiple errors within theme directory
Beginner command line user wants to use Sage theme too!
Gulp Watch / BrowserSync Proxy not using port 3000
Error installing gulp bower and running gulp watch
Gulp is not working correctly
Size of node_modules directory
Deploy fails on npm install
Libsass bindings not found
Main.css, bootstrap, and other assets/resources are not loading in browser
NPM Gulp bug on Ubuntu 14.04 LTS
NPM Gulp bug on Ubuntu 14.04 LTS
Npm install WARN unmet dependency
Gulp/bower installation issues using screencast
High CPU usage with Gulp watch
Installation question


Use nvm to manage node versions

nvm installs node in your user’s home directory without needing superuser privileges. It also allows you to toggle between versions of node effortlessly. You can use nvm to install node on your server as well.

:warning::warning::warning: Do not use sudo with npm :warning::warning::warning:

You may receive an EACCES error when you try to install a package globally. This indicates that you do not have permission to write to the directories that npm uses to store global packages and commands.

The fix is documented here:

Check the Troubleshooting Wiki

Npm install WARN unmet dependency
Gulp, Gulp Watch problem
Gulp Watch / BrowserSync Proxy not using port 3000
If you must update node
Gulp errors (Cannot find module ...)

Additional resources (thanks @amadeo):