You run bun install and it fails with:

error: Failed to install packages

Or sometimes more specific:

error: package "sharp" failed to install

Bun’s package installer is fast, but when it fails, the error messages can be sparse.

What causes this

Bun uses its own package resolution and installation engine, which is different from npm’s. While it’s compatible with most of the npm ecosystem, there are edge cases:

• Packages with native bindings (C/C++ addons) that rely on node-gyp or specific install scripts
• Corrupted local cache
• Lockfile conflicts when switching between Bun and npm/Yarn
• Platform-specific packages that don’t have Bun-compatible binaries
• Network issues during download

Fix 1: Clear cache and reinstall

The first thing to try — wipe everything and start fresh:

bun pm cache rm
rm -rf node_modules bun.lockb
bun install

The bun.lockb file is a binary lockfile. If it’s corrupted or out of sync with your package.json, removing it forces Bun to resolve everything from scratch.

Fix 2: Use verbose output to find the real error

The default error message is often unhelpful. Get more detail:

bun install --verbose

This shows you exactly which package failed and why. Look for errors related to postinstall scripts, missing system dependencies, or network timeouts.

Fix 3: Fall back to npm for problematic packages

Some packages with native bindings (like sharp, bcrypt, or sqlite3) may not work with Bun’s installer. Install them with npm first, then use Bun for everything else:

npm install sharp
bun install

Or add a trustedDependencies field to your package.json to allow lifecycle scripts for specific packages:

{
  "trustedDependencies": ["sharp", "esbuild"]
}

Bun blocks lifecycle scripts (postinstall, etc.) by default for security. If a package needs them to build native code, you have to explicitly trust it.

Fix 4: Update Bun

Bun is evolving fast. Many install issues are fixed in newer versions:

bun upgrade

Check your version with bun --version and compare it against the latest release. If you’re more than a few versions behind, upgrading often resolves mysterious install failures.

Fix 5: Check platform compatibility

Some packages ship platform-specific binaries. If Bun can’t find a binary for your OS/architecture:

# Check what platform Bun is targeting
bun pm ls --all | grep your-package

This is common on ARM-based machines (Apple Silicon, Raspberry Pi) where some packages don’t provide prebuilt binaries yet.

Related resources

• JavaScript array methods cheat sheet
• JavaScript complete guide

How to prevent it

• Keep Bun updated — the installer improves with every release
• Add known problematic packages to trustedDependencies in package.json
• Don’t mix lockfiles — if you’re using Bun, commit bun.lockb and remove package-lock.json or yarn.lock
• Test bun install in CI early so you catch compatibility issues before they block deployments
• Check the Bun compatibility page when adopting packages with native dependencies