Fix: Could Not Find Sharp in Astro

Astro shows “Could not find Sharp” when its default image service can’t load the sharp package. Sharp does the actual resizing and format conversion behind <Image /> and <Picture />. The message says to “install Sharp (sharp) manually into your project or migrate to another image service.” Most of the time, npm install sharp fixes it. If it happens only on your host or in CI, the cause is usually a platform mismatch in the lockfile.

Key Takeaways

• Fix locally with npm install sharp.
• If it fails only in CI or on the host, reinstall with a clean lockfile so the right platform binary is resolved.
• Package managers with strict hoisting (pnpm) may need sharp as a direct dependency.
• If you don’t process images with astro:assets, configure the passthrough image service instead.

Fix 1: install sharp

npm install sharp

Then restart the dev server or rebuild. Adding it as a direct dependency makes sure your package manager installs it where Astro can find it.

Fix 2: platform binaries in CI

Sharp ships prebuilt binaries per operating system and CPU. A lockfile created on an Apple Silicon Mac can, with some package manager setups, skip the Linux binary your CI needs. Symptoms: works locally, “Could not find Sharp” on Netlify, Vercel, Cloudflare or GitHub Actions.

Try, in order:

1. Install in CI with a clean install: npm ci (not a cached node_modules from another OS).
2. Regenerate the lockfile: delete node_modules and package-lock.json, run npm install, commit the new lockfile.
3. Check that optional dependencies aren’t disabled in CI (--omit=optional or npm_config_optional=false will drop sharp’s platform packages).

Sharp’s own installation guide lists cross-platform options for unusual setups.

Fix 3: pnpm and strict installs

With pnpm, packages are only reachable from where they’re declared. If sharp is only a dependency of Astro, add it to your project explicitly:

pnpm add sharp

Fix 4: you don’t need image processing

If you never use <Image />, <Picture /> or getImage() (for example, all images come from a CMS image CDN), skip sharp entirely with the passthrough service:

// astro.config.mjs
import { defineConfig, passthroughImageService } from 'astro/config';

export default defineConfig({
  image: { service: passthroughImageService() },
});

Images still render, but Astro won’t resize or convert them.

Serverless and edge runtimes

On-demand image processing in some edge runtimes can’t use sharp’s native binaries. In that case, prerender pages with images, or use the image service provided by your adapter or host. The Astro deploy guide covers host differences, and faster Astro builds in CI covers caching processed images so sharp has less to do. For what image processing gives you, see the Astro performance guide. The official entry is in the Astro error reference.

FAQ

Do I need sharp for a static Astro site?

Only if you use astro:assets to process images, which is the default for <Image />. A site with no processed images can use the passthrough service.

Why did this start after upgrading Node?

Native binaries are tied to platform and sometimes Node versions. Reinstall dependencies after changing Node versions.