Build from source fails on Node.js 24 LTS with globally-installed libvips

[jechol]

Possible install-time or require-time problem

• I have read and understood all of the documentation relating to installation.
• I have searched for known bugs relating to this problem in my choice of package manager.

Are you using the latest version of sharp?

• I am using the latest version of sharp as reported by npm view sharp dist-tags.latest (0.34.5).

Are you using a supported runtime?

• I am using Node.js with a version that satisfies ^18.17.0 || ^20.3.0 || >=21.0.0

Are you using a supported package manager and installing optional dependencies?

• I am using npm >= 10.1.0 with --include=optional

What is the complete error message, including the full stack trace?

When libvips is globally installed (e.g. via brew install vips), sharp attempts to build from source instead of using prebuilt binaries. This fails on Node.js 24 LTS:

sharp: Attempting to build from source via node-gyp
sharp: Detected globally-installed libvips v8.18.0
../metadata.cc:259:46: error: no member named 'NewOrCopy' in 'Napi::Buffer<char>'
../metadata.cc:262:45: error: no member named 'NewOrCopy' in 'Napi::Buffer<char>'
../metadata.cc:265:46: error: no member named 'NewOrCopy' in 'Napi::Buffer<char>'
../metadata.cc:272:45: error: no member named 'NewOrCopy' in 'Napi::Buffer<char>'
../metadata.cc:276:31: error: no member named 'NewOrCopy' in 'Napi::Buffer<char>'
5 errors generated.
make: *** [Release/obj.target/sharp-darwin-arm64/metadata.o] Error 1
gyp ERR! build error

What is the complete output of running npm install --verbose --foreground-scripts sharp in an empty directory?

Details

sharp: Attempting to build from source via node-gyp
sharp: See https://sharp.pixelplumbing.com/install#building-from-source
sharp: Please add node-addon-api to your dependencies
npm error code 1
npm error path /private/tmp/sharp-test/node_modules/sharp
npm error command failed
npm error command sh -c node install/check.js || npm run build

What is the output of running npx envinfo --binaries --system --npmPackages=sharp --npmGlobalPackages=sharp?

System:
  OS: macOS 26.2
  CPU: (10) arm64 Apple M1 Pro
  Memory: 110.91 MB / 16.00 GB
  Shell: 5.9 - /bin/zsh
Binaries:
  Node: 24.13.0
  npm: 11.6.2

Workaround: SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install sharp forces prebuilt binary download and succeeds.

[lovell]

Is your desired outcome to:

1. use prebuilt libvips binaries on a machine with a globally-installed libvips
2. successfully build sharp against a globally-installed libvips
3. something else

?

[DanielSWolf]

I can't speak for the OP, but we're having the problem that depending on machine configuration, sometimes sharp will try to build from sources. When that happens, it fails because of the missing node-addon-api package. So we ended up adding node-addon-api to our own dependencies for no other reason than to make sure sharp can install correctly.

[Jeremiah-England]

I ran into this issue today. My desired behavior is (1). I think the only way to achieve that is via the SHARP_IGNORE_GLOBAL_LIBVIPS environment variable.

In general, that seems fine. But with the current state of the Javascript ecosystem it's kind of painful (if I'm understanding things correctly). The package.json format does not support adding environment variables when building specific dependencies the way uv/pyproject.toml does.

I had a conversation with Grok about it and it looks like there are quite a few of options sharp has for making this easier.

• https://grok.com/share/bGVnYWN5LWNvcHk_448b82a7-2676-4640-8afc-9a0b0b2c0603

Ideally, I would like a solution that selects behavior (1) in a way that I can commit to a repository for the sake of other developers without writing non-standard install scripts. Right now I have told other people working on the project to export SHARP_IGNORE_GLOBAL_LIBVIPS in their shell profile if they run into the issue, which seems really sub-optimal.

Please inform me if I'm overlooking an existing easy solution here!

[lovell]

Building from source will be opt-in from the next release, please see #4490 (comment)

[axgoodhart]

This has been repeatedly an issue for me as well in Node 24 and Node 22. I found that running

brew unlink vips

before running npm install temporarily fixes the issue.