Running Compass on a Windows environment

Compass is a popular Sass framework which offers some really useful features. This post is intended to explain how to get Compass up and running on a Windows environment from a technical point of view, if you’d like to know more about the benefits of using Compass having a read of Why SASS and Compass should be in your workflow.

If you’re thinking of trying out Compass for the first time or in my case, trying to get a 3rd party project build, then you’ll probably run into the same issues that I did unless of course your environment is already configured correctly.

If you’re familiar with compiling Sass with Gulp or Grunt build tasks then it’s reasonable to expect that you could just install the gulp-compass NPM package and use it in-place of gulp-sass and off you go. If you do this you will be confronted with this error message;

Warning: You need to have Ruby and Compass installed and in your PATH for system path for this task to work

So this was the point of realisation for myself – Even though NPM is built on NodeJS, that doesn’t mean NPM packages are limited to executing node applications. *TODO: Find blog article* Compass is built on Ruby which is a completely separate and unaffiliated runtime environment to NodeJS. Ruby provides it’s own package manager called Rubygems, which works just like NPM does is for NodeJS. 

So to put it clearly, the gulp-compass NPM package has a dependency of the Compass Gem, which has a dependency on the Ruby runtime.

As a primarily Microsoft developer for 16 years it makes me ask wwwwwwhyy!? After sitting back and digesting it all it does make sense when you realise that Ruby is native to Mac OSX and other nix based OS. If your working in those environments you’re simply installing a gem with one command in the CLI. Although it’s just as easy in Windows once you’ve installed the Ruby runtime.

Here’s a rundown on how to install Compass on a Windows environment. This assumes that you already have NodeJS and NPM installed.

Install Ruby

Download the Ruby Installer and run the installer.

Make sure that "Install at PATH option is checked"

Make sure that “Add Ruby executables to your PATH” option is checked

Once installed, confirm that Ruby is installed globally by typing “ruby -v” in the Windows CLI.  If the command isn’t recognised try opening a new CLI window in Admin Mode and re-try the command. If this still doesn’t work then Ruby probably it’s not in the PATH. Try either reinstalling Ruby  with “install at PATH” option checked, or manually add the Ruby path in the Windows Environment Variables.

Install Compass Gem

Install Compass via Ruby using the windows CLI.

gem install compass

Using the Windows CLI run the following command.

Confirm that compass is installed by typing compass -v in the Windows CLI. You should now see the version


Note: The Compass GEM has been installed globally, unlike NPM where it defaults to installing the package to the current directory.

Installing Gulp-Compass

So now that the dependencies are configured, you’re now ready to build Compass Sass. If you’re familiar with gulpjs and NPM the rest of this should be what you’re used to.

Install the gulp-compass package like any other NPM package.

npm install gulp-compass --savedev

Basic Gulp Usage

Basic example using gulp-compass to compile sass instead of the regular gulp-sass package.

 NPM packages

  "name": "Website",
  "version": "0.0.0",
    "devDependencies": {
    "gulp": "^3.9.1",
    "gulp-compass": "^2.1.0"

Gulp Script

var gulp = require('gulp');
var compass = require('gulp-compass');

gulp.task('compass', function () {
    return gulp.src('./website/sass/*.scss')
           css: './website/stylesheets',
           sass: './website/sass',

gulp.task('watch-compass', function () {
    return'./website/sass/*.scss', ['compass']);



Here are all the dependancies and versions that I used at the time of writing.

Dependency Type Tested Version
Windows 10 Operating System v10
Node.js Runtime Environment v4.5.0
NPM  Node.JS Pluggin v2.15.9
Ruby Runtime Environment v2.3.1 (x64)
Compass  Ruby Package v1.0.3
Gulp NPM Package v3.9.1
Gulp-Compass NPM Package v2.1.0

Leave a Reply

Your email address will not be published. Required fields are marked *