How to fix npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@2.3.2 (node_modules/fsevents) in npm

npmBEGINNERLOWUpdated Dec 6, 2025· 175 views

This warning appears when npm skips installing fsevents on non-macOS systems. It is safe to ignore—fsevents is a macOS-only file watching library that is not needed on Windows or Linux.

Quick fix

Fixes npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@2.3.2 (node_modules/fsevents)

# Skip optional dependencies during install
npm install --omit=optional

# Or set in .npmrc
echo "omit=optional" >> .npmrc
  1. Understand this is safe to ignore
  2. Suppress warnings with --omit=optional
  3. Upgrade npm for quieter output
  4. Clean reinstall if concerned
npm — error
# Skip optional dependencies during install
npm install --omit=optional
# Or set in .npmrc
echo "omit=optional" >> .npmrc
npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@2.3.2 (node_modules/fsevents)

What this error means

This message is a warning, not an error—your installation completed successfully. fsevents is a native macOS library that provides efficient file system event monitoring. It's marked as an optional dependency by packages like Chokidar (used by webpack, Vite, Jest, and many other tools). When npm detects you're running on Windows, Linux, WSL, or a Docker container, it correctly skips fsevents installation because the library only works on macOS. The packages that depend on fsevents have fallback mechanisms (usually polling-based file watching) that work on all platforms.

Typical symptoms

  • Warning appears during npm install or npm ci
  • Message mentions "Unsupported platform" with wanted os: darwin
  • Warning shows current OS as win32 or linux
  • Installation completes successfully despite the warning
  • Warning appears repeatedly for transitive dependencies
  • No actual functionality is broken

Common causes

  1. Installing on Windows, Linux, or WSL instead of macOS
  2. Running npm install in Docker containers (usually Linux-based)
  3. CI/CD runners using Linux agents (most common setup)
  4. Transitive dependency from Chokidar, webpack, or file watching tools
  5. fsevents listed as optionalDependency in a dependency chain

How to fix "npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@2.3.2 (node_modules/fsevents)"

1Understand this is safe to ignore

This warning is informational only. Your project will work correctly:

- On macOS: fsevents installs and provides native file watching
- On Windows/Linux: fsevents is skipped, tools use polling fallback

No action is required unless you want to suppress the warning.

2Suppress warnings with --omit=optional

If the warnings are distracting, skip optional dependencies:

bash
# Skip optional dependencies during install
npm install --omit=optional

# Or set in .npmrc
echo "omit=optional" >> .npmrc

Note: This may skip other optional dependencies you actually want.

3Upgrade npm for quieter output

npm 7+ handles optional dependencies more gracefully:

bash
# Check npm version
npm -v

# Upgrade npm
npm install -g npm@latest

Newer npm versions produce less verbose optional dependency warnings.

4Clean reinstall if concerned

If you want a fresh installation to clear any cached state:

bash
# Remove existing installation
rm -rf node_modules package-lock.json

# Clear npm cache
npm cache clean --force

# Reinstall
npm install

The warning will still appear, but installation will be clean.

5Verify project works correctly

Test that file watching works in your project:

bash
# For webpack projects
npm run dev  # or npm start

# For Jest with watch mode
npm test -- --watch

# For Vite projects
npm run dev

Hot reload and file watching should work normally without fsevents.

Advanced notes

Performance implications: On macOS, fsevents uses native APIs for efficient file system monitoring. On other platforms, tools typically fall back to polling (checking files periodically) which uses slightly more CPU but is functionally equivalent.

For large projects on Windows/Linux, you may notice slightly higher CPU usage during development due to polling. This is normal and rarely problematic for most projects.

In Docker development environments, consider using volume mount options that improve file watching performance, such as :delegated or :cached flags on macOS Docker Desktop, or using native Linux filesystems for the project directory.

Frequently asked questions

What does "npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@2.3.2 (node_m" mean?
This message is a warning, not an error—your installation completed successfully. fsevents is a native macOS library that provides efficient file system event monitoring. It's marked as an optional dependency by packages like Chokidar (used by webpack, Vite, Jest, and many other tools).
How do I fix "npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@2.3.2 (node_m"?
This warning appears when npm skips installing fsevents on non-macOS systems. It is safe to ignore—fsevents is a macOS-only file watching library that is not needed on Windows or Linux.
What causes "npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@2.3.2 (node_m"?
Installing on Windows, Linux, or WSL instead of macOS Running npm install in Docker containers (usually Linux-based) CI/CD runners using Linux agents (most common setup)
Is the "npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@2.3.2 (node_m" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading