sharp Install Failed (Image Processing) - Fix in CI

By Daniel Zoghalchali·Latchkey

sharp ships platform-specific native binaries. When the runner platform has no prebuilt binary, or the download is blocked by the network, the install or load fails. Managed runners (Latchkey) that match your target platform and auto-retry transient network failures avoid the flaky-download class of this error.

What this error means

Install or build fails with Could not load the "sharp" module or a sharp install/download error.

Error: Could not load the "sharp" module using the linux-x64 runtime
Possible solutions:
- Ensure optional dependencies can be installed:
    npm install --include=optional sharp

Common causes

Optional dependencies skipped

sharp's platform binary is an optional dependency; --no-optional or a lockfile from another OS omits it.

Blocked or flaky binary download

The runner network blocked or dropped the prebuilt binary fetch.

How to fix it

Install with optional deps for the platform

1. Include optional dependencies and the correct platform binary.

npm install --include=optional sharp

Pin the platform in the lockfile

1. Commit a lockfile generated for the CI platform, or add the platform-specific sharp package.

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

How to prevent it

• Generate the lockfile on a platform matching CI, or include all platform binaries.
• Run image-processing builds on a runner whose platform matches your targets.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation