[Bug] v13: `npm install` on Windows still invokes Python/node-gyp even when bundled prebuilt exists

[greg-hammond]

[Bug] v13: npm install on Windows still invokes Python/node-gyp even when bundled prebuilt exists

---

Description

Version: 13.0.0 / 13.0.1
Platform: Windows (win32-x64)
Severity: Breaks install for all Windows users without a full C++ / Python toolchain

---

What happens

Installing better-sqlite3@13 on Windows without Python and Visual C++ Build Tools fails:

gyp ERR! find Python
gyp ERR! find Python Python is not set from command line or npm configuration
gyp ERR! find Python Python is not set from the environment variable PYTHON
gyp ERR! find Python ...
gyp ERR! not ok

This occurs even though prebuilds/win32-x64.node is included in the published package and is ready to use — no compilation is necessary.

---

Root cause

package.json in v13 has no install script. When npm/pnpm encounters a binding.gyp without an install script, it automatically invokes node-gyp rebuild as the implicit install script.

node-gyp rebuild requires Python in order to run the GYP configure step — and the configure step must run before GYP can evaluate any variables, including the prebuild_exists detection in binding.gyp:

# npm's implicit node-gyp rebuild should do nothing when the package
# contains a prebuild for the host. Explicit build scripts override this.
'force_build%': 0,
'prebuild_exists%': '<!@(node lib/binding.js)',

The intent here is clearly correct — if prebuild_exists is 1, the build is skipped. But Python is consumed before this check can happen. The prebuilt detection therefore never prevents Python from being required.

---

The v12 behavior (correct)

v12 used prebuild-install as the install script. prebuild-install runs entirely in Node.js and checks for the bundled binary before node-gyp is ever touched. If the prebuilt is found, it exits 0 immediately — Python is never needed.

---

Suggested fix

Add a minimal install script (node install.js or similar) that:

1. Calls getPrebuildPath() from lib/binding.js (already exported).
2. If a prebuilt is found, exits 0 immediately.
3. Only if no prebuilt is found, falls through to node-gyp rebuild.

The logic already exists in lib/binding.js — it just needs to be the entry point rather than buried inside the GYP build system:

// install.js
'use strict';
const { getPrebuildPath } = require('./lib/binding');

if (getPrebuildPath()) {
  // Prebuilt binary found — nothing to do.
  process.exit(0);
}

// No prebuilt for this platform/arch — compile from source.
const { execFileSync } = require('child_process');
execFileSync(process.execPath, [
  require.resolve('node-gyp/bin/node-gyp.js'),
  'rebuild',
], { stdio: 'inherit' });

And in package.json:

"scripts": {
  "install": "node install.js"
}

---

Workaround (for affected users)

If you cannot install v13, stay on v12:

npm install better-sqlite3@^12

v12 ships Node.js 24/26 prebuilts and behaves correctly on Windows without a build toolchain.

---

This effectively reverts the Windows install experience to broken for the majority of users who don't have Python and MSVC installed, despite the package bundling a ready-to-use binary. It would be great to get this resolved in a v13.0.2 patch.

---

Full disclosure: this issue was written with the help of an LLM, after troubleshooting the issue together.

[joshkel]

We're running into what I believe is the same root issue. When we run yarn install on a node:24-trixie-slim Docker image (which doesn't have any build toolchains), we get errors about Python missing.

As I understand it, this is the same cause: the prebuilt binaries are present, and node-gyp is able to find and resolve them, but node-gyp itself is unable to run without some portion of the build toolchain.

yarn install output

gyp info it worked if it ends with ok
gyp info using node-gyp@10.0.0
gyp info using node@24.18.0 | linux | x64
gyp ERR! find Python 
gyp ERR! find Python Python is not set from command line or npm configuration
gyp ERR! find Python Python is not set from environment variable PYTHON
gyp ERR! find Python checking if "python3" can be used
gyp ERR! find Python - executable path is ""
gyp ERR! find Python - "" could not be run
gyp ERR! find Python checking if "python" can be used
gyp ERR! find Python - executable path is ""
gyp ERR! find Python - "" could not be run
gyp ERR! find Python 
gyp ERR! find Python **********************************************************
gyp ERR! find Python You need to install the latest version of Python.
gyp ERR! find Python Node-gyp should be able to find and use Python. If not,
gyp ERR! find Python you can try one of the following options:
gyp ERR! find Python - Use the switch --python="/path/to/pythonexecutable"
gyp ERR! find Python (accepted by both node-gyp and npm)
gyp ERR! find Python - Set the environment variable PYTHON
gyp ERR! find Python - Set the npm configuration variable python:
gyp ERR! find Python npm config set python "/path/to/pythonexecutable"
gyp ERR! find Python For more information consult the documentation at:
gyp ERR! find Python https://github.com/nodejs/node-gyp#installation
gyp ERR! find Python **********************************************************
gyp ERR! find Python 
gyp ERR! configure error 
gyp ERR! stack Error: Could not find any Python installation to use
gyp ERR! stack at PythonFinder.fail (/builds/mycompany/myproject/node_modules/node-gyp/lib/find-python.js:306:11)
gyp ERR! stack at PythonFinder.findPython (/builds/mycompany/myproject/node_modules/node-gyp/lib/find-python.js:164:17)
gyp ERR! stack at process.processTicksAndRejections (node:internal/process/task_queues:104:5)
gyp ERR! stack at async configure (/builds/mycompany/myproject/node_modules/node-gyp/lib/configure.js:22:18)
gyp ERR! stack at async run (/builds/mycompany/myproject/node_modules/node-gyp/bin/node-gyp.js:81:18)
gyp ERR! System Linux 5.15.154+
gyp ERR! command "/usr/local/bin/node" "/builds/mycompany/myproject/node_modules/node-gyp/bin/node-gyp.js" "rebuild"
gyp ERR! cwd /builds/mycompany/myproject/node_modules/better-sqlite3
gyp ERR! node -v v24.18.0
gyp ERR! node-gyp -v v10.0.0
gyp ERR! not ok

[joshkel]

As a workaround for Yarn Berry (Yarn Modern), you can add a dependenciesMeta block to your package.json with the following contents:

{
  "dependenciesMeta": {
    "better-sqlite3": {
      "built": false
    }
  }
}

This forces Yarn to use the prebuilt binary instead of invoking node-gyp itself.

I know that PNPM and the latest NPM versions are also taking steps to lock down build scripts, so they may have similar options.

[JoshuaWise]

The recent change was prompted due to NPM dropping support for install scripts. See #1481

[greg-hammond]

@JoshuaWise I dug into this a bit more with AI.

It seems that at publish time, npm publish code will itself ADD AN INSTALL SCRIPT to the manifest.

If a package has binding.gyp but no install/preinstall script, npm injects "install": "node-gyp rebuild"
and "gypfile": true into the registry manifest.

So it seems that the deletion of the install script in v13 is
paradoxically what TRIGGERED the install script to make it into the published package.

We can prove the above by inspecting https://registry.npmjs.org/better-sqlite3/13.0.1 - npm did indeed add an install script:

"scripts":{
"build-release":"node-gyp clean && node-gyp rebuild --release --force_build=1",
"build-debug":"node-gyp clean && node-gyp rebuild --debug --force_build=1",
"test":"mocha --exit --slow=75 --timeout=5000",
"benchmark":"node benchmark",
"download":"bash ./deps/download.sh",
"clean":"rm -rf node_modules build prebuilds",
"install":"node-gyp rebuild"   // <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

LLM suggested fix

better-sqlite3 should specify gypfile=false in package.json

{
  "name": "better-sqlite3",
  "version": "13.0.1",
  "gypfile": false,    // <<<<<<<<<<<<<<<<<<<<<<<<<<<

Workaround (for pnpm users)

manually edit pnpm-workspace.yaml and set better-sqlite3: false PRIOR to updating better-sqlite3 to v13.0.1. Apparently just removing it does not work.

[neoxpert]

Just for reference: npm gypfile option

So I second the suggestion of adding this option, if getting rid of the install script is the goal to achieve.

[EDM115]

I can confirm that setting this in the pnpm-workspace.yaml fixes it (on platforms that ships the prebuilt at least) :

allowBuilds:
  better-sqlite3: false