sharp fails to load on Windows after npm install (Strapi, Next.js, Node.js)
Could not load the "sharp" module using the win32-x64 runtimeShort 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.
Fix it fast
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 omit2Match what you see, then jump to its fix
- 1
npm config get omit prints optional, or the install ran with --omit=optionalOptional dependencies are being skippedFix - 2
The project was installed on macOS or Linux, or in Docker, then copied to Windowsnode_modules or the lockfile came from another operating systemFix - 3
You 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
node --version prints a version below 20.9, often after nvm switched the active versionThe Node.js version is older than sharp supportsFix
- 1
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 sharp3Verify
Load the module once.
node -e "console.log(require('sharp').versions)"Confirmed by docs.npmjs.com
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\@img2Fix
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 install3Verify
The @img folder lists a win32-x64 package, and sharp loads.
dir node_modules\@img
node -e "require('sharp')"Confirmed by sharp.pixelplumbing.com
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 sharp3Verify
Run the app on the target machine.
node -e "require('sharp')"Confirmed by sharp.pixelplumbing.com
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 --version2Fix
Switch to a supported Node.js, then reinstall so the right packages are fetched.
nvm use 22
rmdir /s /q node_modules
npm install3Verify
Load sharp under the new version.
node -e "console.log(process.version, require('sharp').versions.sharp)"Confirmed by sharp.pixelplumbing.com
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
Back end
create-next-app keeps creating a TypeScript project
Would you like to use TypeScript? No / Yes
create-next-app now makes a TypeScript project by default.
2 causes, each with a fixBack end
Show a custom sign-in error in NextAuth without leaving the page
http://localhost:3000/api/auth/error?error=...
By default a failed NextAuth credentials sign-in navigates to the error page with the message in the URL.
3 causes, each with a fixBack end
Request body is rejected as too large in Next.js (1 MB default)
413 Payload Too Large
Next.js limits request bodies to 1 MB by default, in both Pages Router API routes and Server Actions.
3 causes, each with a fixBack end
Next.js server code cannot connect to its own API on 127.0.0.1
Error: connect ECONNREFUSED 127.0.0.1:3003
ECONNREFUSED means nothing was listening at that address and port when the server-side fetch ran.
2 causes, each with a fixBack end
next build stops with: Failed to collect page data for a route
Error: Failed to collect page data for /dashboard
Failed to collect page data for a route is the last line of a failed build, not the cause.
3 causes, each with a fixBack end
TypeError: Failed to parse URL when a Next.js server fetches its own API
TypeError: Failed to parse URL from undefined/api/test
Server code has no page address, so fetch('/api/test') cannot be turned into a full URL and throws Failed to parse URL.
3 causes, each with a fix