npm ERR! code EBADPLATFORM

The package is designed for a different operating system or CPU architecture.

Frequently documented in developer and vendor support forums.

• Windows-only package on Linux
• x64 package on ARM system
• OS-specific native modules

1. Find cross-platform alternative
2. Use platform-specific version
3. Build from source for your platform

Last reviewed: March 2026 How we review solutions

EBADPLATFORM fires when a package declares operating system or CPU architecture restrictions in its package.json and your current platform does not match. Package authors use the "os" field (e.g., ["linux", "darwin"]) and "cpu" field (e.g., ["x64", "arm64"]) to declare supported platforms. When npm encounters a package whose platform requirements exclude your system, it refuses to install it rather than downloading code that cannot possibly run. This is especially common with native binary packages that include pre-compiled binaries for specific OS/architecture combinations—packages like sharp (image processing), better-sqlite3, or fsevents (macOS-only file watching). The fsevents package is the single most common source of EBADPLATFORM: it is listed as a dependency by many popular tools (Webpack, Vite, Jest) but only works on macOS. Most of these tools list fsevents as an optional dependency so it skips silently on Linux and Windows, but if a lockfile was generated on macOS and you install on Linux, the explicit entry in the lockfile can trigger this error. Cross-platform development teams encounter this regularly when sharing lockfiles between macOS and Linux developers.

1. Check which package triggered the error in the npm output
2. View the package's os and cpu fields: npm view package-name os cpu
3. Verify your platform: node -p "process.platform + ' ' + process.arch"
4. If the package is optional, use npm install --ignore-optional
5. Delete package-lock.json and regenerate on your platform: npm install

Docker on Apple Silicon building for amd64

When building Docker images on M1/M2 Macs with --platform=linux/amd64, npm sees the emulated amd64 architecture. Packages with "cpu": ["arm64"] will fail. Use multi-stage builds or install with --ignore-optional inside the container.

Windows WSL mixing npm contexts

Running npm install in WSL installs Linux packages, but running node from Windows cmd uses the Windows Node. If you mix these, platform-specific packages installed for Linux will fail on Windows Node. Keep your entire workflow within WSL or Windows, not both.

Lockfile generated on different OS

package-lock.json includes resolved URLs for platform-specific packages. A lockfile generated on macOS may include darwin-only entries that fail on Linux CI. Delete and regenerate the lockfile on your CI platform, or use npm ci with --ignore-optional.

Can I force install anyway?

Use --force but the package likely won't work correctly.

How do I check platform support?

Check the package.json os and cpu fields in the package.

What is fsevents and why is it everywhere?

fsevents is a macOS-specific package that provides efficient file system change notifications. Tools like Webpack, Vite, and Jest depend on chokidar for file watching, which lists fsevents as an optional dependency. It is intentionally macOS-only and safely skips on other platforms.

How do I force install a package on an unsupported platform?

Use npm install --force to bypass platform checks. The package will install but may not work correctly since it was not designed for your platform. Only use this if you know the platform restriction is overly conservative.

Can I exclude platform-specific packages in my project?

Move them to optionalDependencies in your package.json. npm treats optional dependencies as non-fatal—if they fail to install due to platform mismatch, npm continues without them.

• npm install – Official npm Docs
• package.json Reference – npm Docs