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

npmBEGINNERLOWUpdated Dec 5, 2025· 216 views

This warning appears on Linux and Windows because fsevents is a macOS-only file watching library. This is completely safe to ignore—npm correctly skips the dependency, and your application works normally without it.

Quick fix

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

# Run npm install normally - this is safe to do
npm install

# The warning will appear but installation completes successfully
# Your application works exactly as expected
  1. Understand it's safe to ignore
  2. Suppress the warning with --omit flag (npm v7+)
  3. Suppress the warning with --no-optional flag (npm v6 and earlier)
  4. Update npm to the latest version
npm — error
# Run npm install normally - this is safe to do
npm install
# The warning will appear but installation completes successfully
# Your application works exactly as expected
npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@2.3.2 (node_modules/fsevents): unsupported platform

What this error means

The "npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents" warning appears during npm install on Linux and Windows systems. fsevents is a native Node.js module that provides high-performance file system event monitoring exclusively for macOS via the FSEvents API. Since the FSEvents API doesn't exist on Linux or Windows, npm correctly skips installing this package on those platforms. This is a **warning, not an error**—your application will function normally without this module, as the package that depends on fsevents (typically file watchers like Chokidar) is designed to gracefully degrade and use alternative mechanisms on non-macOS systems. The warning is npm's way of being verbose about platform-specific dependencies. Optional dependencies are intentionally designed to improve performance in specific environments while allowing the application to work correctly without them.

Typical symptoms

  • npm install or npm ci completes successfully but displays 'WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents' on Linux or Windows
  • The warning appears even though npm install runs without errors and your project works correctly
  • File watching features in development (hot reload, test watchers) function normally despite the warning
  • The warning disappears when running npm install on a macOS machine (where fsevents actually installs)
  • CI/CD pipelines on Linux containers display this warning repeatedly but pass all subsequent build steps

Common causes

  1. Platform-specific native module: fsevents is a native C++ module compiled only for macOS that uses the proprietary FSEvents API
  2. Optional dependency declaration: The package is correctly marked as optionalDependencies by libraries like Chokidar
  3. npm detecting unsupported platform: npm performs platform checks during installation and correctly identifies Linux/Windows cannot support this macOS-only module
  4. Package-lock.json including platform-specific entries: Your package-lock.json may contain entries for all platforms including macOS
  5. Transitive optional dependencies: The warning often appears for fsevents in nested dependencies rather than direct project dependencies

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

1Understand it's safe to ignore

The warning is purely informational and does not affect your application. npm's behavior is correct—it's simply notifying you that an optional platform-specific dependency was skipped because it's unsupported on your OS.

bash
# Run npm install normally - this is safe to do
npm install

# The warning will appear but installation completes successfully
# Your application works exactly as expected

No action is required—your application functions identically whether or not you see this warning.

2Suppress the warning with --omit flag (npm v7+)

For npm version 7 and later, use the --omit=optional flag to skip optional dependencies entirely during installation:

bash
npm install --omit=optional

Or as an environment-level setting in .npmrc:

bash
echo "omit=optional" >> ~/.npmrc

This prevents npm from even attempting to resolve optional dependencies, eliminating the warning entirely.

3Suppress the warning with --no-optional flag (npm v6 and earlier)

If you're using an older version of npm, you can skip optional dependencies using the deprecated --no-optional flag:

bash
npm install --no-optional

Note: This flag is deprecated in newer npm versions—use --omit=optional instead if available.

4Update npm to the latest version

Newer versions of npm handle optional platform-specific dependencies more gracefully and display less intrusive warnings:

bash
npm install -g npm@latest

# Then run your regular install
npm install

Newer npm versions are quieter about expected platform skips.

5For CI/CD pipelines, add npm config for cleaner logs

In your CI/CD configuration or .npmrc file, suppress this specific warning category:

bash
# In .npmrc or CI pipeline setup:
warn-only-once=true

# Or configure npm to emit warnings less verbosely:
npm config set loglevel=warn

This keeps your CI/CD logs cleaner without affecting functionality.

6No action needed - accept the warning as normal

The simplest solution is to accept this warning as expected behavior. Modern development practices recognize that platform-specific optional dependencies skipping is the correct behavior:

bash
# Just run normally and ignore the warning
npm install

# Everything works fine - the warning is just information
npm run dev

Your application functions identically whether you suppress the warning or not.

Advanced notes

fsevents is a native N-API module that wraps macOS's low-level FSEvents API, which monitors file system activity at the kernel level. This gives macOS applications much better performance for file watching compared to polling approaches. On Linux, applications typically use inotify (via libraries like Chokidar), and on Windows, ReadDirectoryChangesW handles file monitoring. These are fundamentally different mechanisms, so the dependency cannot be cross-compiled or emulated—it must be skipped on unsupported platforms.

Optional dependencies (optionalDependencies in package.json) are the correct npm mechanism for this pattern: they allow a package to gracefully work on multiple platforms while using platform-specific optimizations where available. Packages like Chokidar deliberately list fsevents as optional and include fallback logic—the package detects at runtime whether fsevents is available and uses it if present, otherwise falls back to cross-platform alternatives.

Some developers report that deleting node_modules and package-lock.json then running npm install fresh can help if the warning becomes problematic in specific environments, though this is rarely necessary.

Frequently asked questions

What does "npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@2.3.2 (node_m" mean?
The "npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents" warning appears during npm install on Linux and Windows systems. js module that provides high-performance file system event monitoring exclusively for macOS via the FSEvents API. Since the FSEvents API doesn't exist on Linux or Windows, npm correctly skips installing this package on those platforms.
How do I fix "npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@2.3.2 (node_m"?
This warning appears on Linux and Windows because fsevents is a macOS-only file watching library. This is completely safe to ignore—npm correctly skips the dependency, and your application works normally without it.
What causes "npm WARN optional SKIPPING OPTIONAL DEPENDENCY: fsevents@2.3.2 (node_m"?
Platform-specific native module: fsevents is a native C++ module compiled only for macOS that uses the proprietary FSEvents API Optional dependency declaration: The package is correctly marked as optionalDependencies by libraries like Chokidar npm detecting unsupported platform: npm performs platform checks during installation and correctly identifies Linux/Windows cannot support this macOS-only module
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