Installing Headstart

First time users: Headstart runs on NodeJS and uses Sass for compilation. Make sure your system meets the requirements before continuing.

Headstart lives in the command line. If you've never opened or worked with it before, don't worry about it too much. You'll only be using it to pass in installation and build instructions.

Open up any command line application and install Headstart globally. Using -g will enable usage of the build commands from any directory.

npm install -g headstart

If you get a Permission denied or Error: EACCES error, you should run the previous command again in sudo:

sudo npm install -g headstart

There is some discussion about whether or not usage of sudo is a good thing, but it' the easiest way to get around it. If you are working on a shared machine, it might be good to look into an alternative solution.

When NPM finishes downloading and installing Headstart and all of its dependencies (grab a coffee!), run the following command to get a quick overview of all the available commands:


Next step: Starting a new project


Headstart is built with open-source software, so you are required to install a few things before you can get started. But that's only small trade-off for all the benefits you get!

Command Line

Headstart can be used through a Command Line Interface (CLI). Depending on your Operating System, you will probably end up using one of following command line applications:


Check if you have Ruby installed by running:

ruby -v

If any version of Ruby is printed out, you are good to go. If you see command not found appear, you can follow the instructions on this page to install Ruby.


Sass is used to compile .scss files into CSS. You can check if Sass has been installed by running:

sass -v

If any version of Sass is printed out, you are good to go. If you see command not found appear, you can install Sass by running:

gem install sass

NodeJS and NPM

NodeJS is usd to run the modules that make up Headstart. NPM (Node Packaged Modules) is the package manager that comes with Node.

You can download the appropriate installer through the NodeJS website.


Some NodeJS module authors aren't as responsive as others, so some Headstart updates might retrieve modules directly from Github, rather than through NPM. For this reason, it is advised to install Git. You can check if you have it installed by running:

git --version

If any version of Git is printed out, you are good to go. If you see command not found appear, you can download the installer through the Git website.

Command Line Tools

Not as much a requirement, but included here just in case. If you work with a Mac, it is possible that you'll be asked to install the Command Line tools through Xcode. Don' worry though, there is a way to install them without getting your hands on the full application:

xcode-select --install

This will open up a Software Update pop-up that will do the searching and installing for you. Just hit install and let it do its job.

That's all!

Once your machine meets all of the requirements, jump back up and install Headstart!