npm install node-sass fails on a current Node.js version
npm install node-sass ends with a gyp build errorShort 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.
Fix it fast
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-sass2Match what you see, then jump to its fix
- 1
Node.js is newer than 20 and the install shows a node-gyp buildnode-sass does not support this Node.js versionFix - 2
The 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
The log shows node-gyp looking for Python, make or a compilerA compile from source fails because the build tools are missingFix
- 1
What does the error look like?
npm install node-sass ends with a gyp build errornode-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-sass2Fix
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 sass3Verify
The install finishes and your build compiles the stylesheets.
npm run buildConfirmed by sass-lang.com
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/null2Fix
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
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 12Fix
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@93Verify
npm ls shows node-sass resolved without errors.
npm ls node-sassConfirmed by raw.githubusercontent.com
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
- Qist BazaarA buy-now-pay-later marketplace built from a blank repo, now past 100K downloads on Google Play.
Related fixes
Back end
Angular build fails with SassError: Undefined variable
SassError: Undefined variable.
Sass modules loaded with @use are scoped to the file that loads them and their variables need a namespace prefix.
4 causes, each with a fixBack end
Sass cannot find a stylesheet imported with a leading ~
File to import not found or unreadable: ~bootstrap/scss/bootstrap
The ~ prefix is not part of Sass.
3 causes, each with a fixBack end
webpack reports Module build failed from sass-loader
Module build failed (from ./node_modules/sass-loader/dist/cjs.js):
The sass-loader line only says which loader failed.
3 causes, each with a fixBack 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 fixBack end
ng fails with Cannot find module @angular/cli/bin/ng
Cannot find module '@angular/cli/bin/ng'
The ng command is the entry point to the Angular CLI package.
2 causes, each with a fixBack end
Angular app shows 'Cannot GET /' when served by a Node.js server
Cannot GET /dashboard
Cannot GET / is Express saying no route or file matches the request.
3 causes, each with a fix