Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

npm install node-sass fails on a current Node.js version

Errornpm install node-sass ends with a gyp build error

Short answer

node-sass is end-of-life and its newest release supports Node.js up to 20, so on newer Node.js the install falls back to a source build that fails. The supported fix is to replace node-sass with the sass package (Dart Sass), which has a matching JavaScript API. Pinning an older Node.js is only a stopgap.

  • Applies to Node.js 22, Node.js 24, npm 10, sass 1.x
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Compare your Node.js version with the supported versions in the node-sass README, and see whether the package is a direct or an indirect dependency.

    node -v
    npm ls node-sass
  2. 2Match what you see, then jump to its fix

    1. 1Node.js is newer than 20 and the install shows a node-gyp buildnode-sass does not support this Node.js versionFix
    2. 2The build fails after the swap with an error about a missing module or a legacy optionCode or a loader still calls the node-sass APIFix
    3. 3The log shows node-gyp looking for Python, make or a compilerA compile from source fails because the build tools are missingFix

What does the error look like?

  • npm install node-sass ends with a gyp build error
  • node-sass fails to install on a recent Node.js version

Cause 1 of 3

node-sass does not support this Node.js version

1Check

The README says node-sass has reached end of life and lists Node 20 with node-sass 9.0+ as the highest supported pair. Node 18 and 19 need node-sass 8.0+.

node -v
npm ls node-sass

2Fix

Replace node-sass with sass. The Sass team's announcement says to swap the dependency in package.json and that the two packages offer matching JavaScript interfaces.

npm uninstall node-sass
npm install sass

3Verify

The install finishes and your build compiles the stylesheets.

npm run build

Confirmed by sass-lang.com

Did this fix it?

Cause 2 of 3

Code or a loader still calls the node-sass API

1Check

The sass package offers compile() and compileString(). Its legacy render API is deprecated but, per the docs, supported until sass 2.0.0.

grep -rn "node-sass\|renderSync" package.json webpack.config.js src/ 2>/dev/null

2Fix

Point the loader or script at sass, and move to compile() when you touch the code.

const sass = require('sass');
const result = sass.compile('src/styles/main.scss');
console.log(result.css);

3Verify

The compiled CSS is written and has the expected rules.

node -e "console.log(require('sass').compile('src/styles/main.scss').css.length)"

Confirmed by sass-lang.com

Did this fix it?

Cause 3 of 3

A compile from source fails because the build tools are missing

1Check

node-gyp's README lists Python, make and a C/C++ toolchain such as GCC as prerequisites on Unix. The node-sass README says it builds from source when its post-install tests fail.

python3 --version
make --version | head -n 1
gcc --version | head -n 1

2Fix

Prefer the sass package, which needs no compilation. If you must keep node-sass for a legacy project on Node.js 20 or older, use release 9 or newer on Node 20, and install the node-gyp prerequisites.

node -v
npm install node-sass@9

3Verify

npm ls shows node-sass resolved without errors.

npm ls node-sass

Confirmed by raw.githubusercontent.com

Did this fix it?

How do I stop it coming back?

  • Use sass for every new project: it is a pure JavaScript package, so installs do not depend on a compiler.
  • Pin the Node.js version in .nvmrc and engines so the whole team installs the same toolchain.
  • Read the Sass JavaScript API notes before raising a major version of sass.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.