Maaz Zindani

Loading the index…

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

sharp fails to load on Windows after npm install (Strapi, Next.js, Node.js)

ErrorCould not load the "sharp" module using the win32-x64 runtime

Short answer

sharp ships its binary as a platform package installed as an optional dependency. The error means the win32-x64 package is missing or the Node.js is too old. Reinstall with optional dependencies included, remove a lockfile or node_modules made on another OS, and run Node.js 20.9 or newer.

  • Applies to sharp (current), Node.js 22, npm 10, Windows
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check the Node.js version and whether npm is set to skip optional dependencies.

    node --version
    npm config get omit
  2. 2Match what you see, then jump to its fix

    1. 1npm config get omit prints optional, or the install ran with --omit=optionalOptional dependencies are being skippedFix
    2. 2The project was installed on macOS or Linux, or in Docker, then copied to Windowsnode_modules or the lockfile came from another operating systemFix
    3. 3You build on one OS and run on another, for example a Windows CI agent building a Linux imageInstalling for a different machine than the one running the codeFix
    4. 4node --version prints a version below 20.9, often after nvm switched the active versionThe Node.js version is older than sharp supportsFix

What does the error look like?

  • Could not load the "sharp" module using the win32-x64 runtime

Cause 1 of 4

Optional dependencies are being skipped

1Check

The sharp install page asks you to make sure your package manager installs optional dependencies. The npm docs say omit lists dependency types left out of the tree on disk, and a type given in both --include and --omit is included.

npm config get omit
echo %npm_config_omit%

2Fix

Reinstall sharp and name optional dependencies explicitly.

npm install --include=optional sharp

3Verify

Load the module once.

node -e "console.log(require('sharp').versions)"

Confirmed by docs.npmjs.com

Did this fix it?

Cause 2 of 4

node_modules or the lockfile came from another operating system

1Check

The sharp docs warn that a package-lock.json shared by several platforms can cause install problems. A lockfile written on another OS can leave the Windows package out.

dir node_modules\@img

2Fix

Delete node_modules and reinstall on the machine that runs the app. If the lockfile is the problem, delete it too and let npm write a fresh one.

rmdir /s /q node_modules
del package-lock.json
npm install

3Verify

The @img folder lists a win32-x64 package, and sharp loads.

dir node_modules\@img
node -e "require('sharp')"

Confirmed by sharp.pixelplumbing.com

Did this fix it?

Cause 3 of 4

Installing for a different machine than the one running the code

1Check

The sharp docs say cross-platform support is limited and uses the --os and --cpu flags, plus --libc when the target is Linux. The npm docs define os and cpu as overrides for the native modules installed.

node -p "process.platform + ' ' + process.arch"

2Fix

Install on the target, or pass the target platform for sharp.

npm install --os=win32 --cpu=x64 sharp

3Verify

Run the app on the target machine.

node -e "require('sharp')"

Confirmed by sharp.pixelplumbing.com

Did this fix it?

Cause 4 of 4

The Node.js version is older than sharp supports

1Check

The sharp install page lists a Node-API v9 compatible runtime, for example Node.js 20.9.0 or newer, as the prerequisite.

node --version

2Fix

Switch to a supported Node.js, then reinstall so the right packages are fetched.

nvm use 22
rmdir /s /q node_modules
npm install

3Verify

Load sharp under the new version.

node -e "console.log(process.version, require('sharp').versions.sharp)"

Confirmed by sharp.pixelplumbing.com

Did this fix it?

How do I stop it coming back?

  • Commit one lockfile, and run npm ci on the OS that runs the app.
  • Keep node_modules out of Git and out of copies between machines.
  • Pin the Node.js version in .nvmrc and in CI.
  • Do not set omit=optional in .npmrc or CI install steps.

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

Next step

Want this handled for good?

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